静态站点死链检测与自动修复实践
【摘要】 前言静态站点随着迭代、图片迁移、页面重构、文档改名,很容易产生大量死链:内部相对路径写错、锚点失效、外部第三方链接下线。人工逐页核对成本极高,放到CI中自动检测,发现问题直接阻断合并,是低成本保障站点可用性的方案。本文实现一套Node脚本,支持扫描HTML、Markdown内链接,区分内部链接/外部链接,支持自动修复简单路径错误,并输出报告。 痛点梳理人工巡检遗漏:锚点#section、相...
前言
静态站点随着迭代、图片迁移、页面重构、文档改名,很容易产生大量死链:内部相对路径写错、锚点失效、外部第三方链接下线。人工逐页核对成本极高,放到CI中自动检测,发现问题直接阻断合并,是低成本保障站点可用性的方案。本文实现一套Node脚本,支持扫描HTML、Markdown内链接,区分内部链接/外部链接,支持自动修复简单路径错误,并输出报告。
痛点梳理
- 人工巡检遗漏:锚点
#section、相对路径../img/xxx.png改动后很难肉眼发现; - 外部链接不可控:第三方文档、图床链接随时失效;
- 仅检测不阻断:发现死链但没有集成到流水线,问题持续堆积;
- 误报干扰:部分链接需要跳过校验(如动态埋点地址、管理后台链接)。
整体设计
- 扫描范围:
*.html、*.md,提取href、src、data-src; - 链接分类:
- 内部链接:相对路径、站内绝对路径,校验本地文件是否存在;
- 锚点链接:同一页面内锚点,校验页面内是否存在对应id;
- 外部链接:http/https,发送HEAD请求探测可用性;
- 白名单:配置skip列表,跳过不需要校验的链接;
- 输出:JSON报告 + 控制台清单,支持CI exit code(发现死链返回非0,阻断流程);
- 自动修复:针对大小写、多余
/、目录层级错误的简单内部链接尝试修正。
完整脚本实现 link-check.js
const fs = require('fs');
const path = require('path');
const { promisify } = require('util');
const readFile = promisify(fs.readFile);
const readdir = promisify(fs.readdir);
const stat = promisify(fs.stat);
const axios = require('axios');
const ROOT = path.resolve(__dirname, './dist');
const SKIP_LIST = [
'[https://analytics.example.com](https://analytics.example.com)',
'#ignore'
];
const report = {
total: 0,
broken: [],
ok: []
};
// 递归遍历目录
async function walk(dir) {
let results = [];
const entries = await readdir(dir);
for (const entry of entries) {
const fullPath = path.join(dir, entry);
const s = await stat(fullPath);
if (s.isDirectory()) {
results = results.concat(await walk(fullPath));
} else if (/\.(html|md)$/.test(entry)) {
results.push(fullPath);
}
}
return results;
}
// 提取链接正则
const linkReg = /(href|src|data-src)=["']([^"']+)["']/g;
function extractLinks(html) {
const links = new Set();
let m;
while ((m = linkReg.exec(html)) !== null) {
links.add(m[2]);
}
return Array.from(links);
}
function isSkip(url) {
return SKIP_LIST.some(item => url.includes(item));
}
async function checkInternalLink(pagePath, targetUrl) {
if (targetUrl.startsWith('#')) {
// 锚点校验
const content = await readFile(pagePath, 'utf8');
const id = targetUrl.slice(1);
return content.includes(`id="${id}"`) || content.includes(`id='${id}'`);
}
const pageDir = path.dirname(pagePath);
const targetPath = path.resolve(pageDir, targetUrl);
try {
await stat(targetPath);
return true;
} catch {
return false;
}
}
async function checkExternalLink(url) {
try {
await axios.head(url, { timeout: 3000 });
return true;
} catch {
return false;
}
}
async function main() {
const files = await walk(ROOT);
for (const file of files) {
const content = await readFile(file, 'utf8');
const links = extractLinks(content);
for (const link of links) {
report.total++;
if (isSkip(link)) {
report.ok.push({ file, link, status: 'skipped' });
continue;
}
let valid = false;
if (link.startsWith('http://') || link.startsWith('https://')) {
valid = await checkExternalLink(link);
} else {
valid = await checkInternalLink(file, link);
}
if (valid) {
report.ok.push({ file, link, status: 'ok' });
} else {
report.broken.push({ file, link });
}
}
}
console.log(JSON.stringify(report, null, 2));
if (report.broken.length > 0) {
console.error(`❌ 发现 ${report.broken.length} 条死链!`);
process.exit(1);
} else {
console.log('✅ 所有链接校验通过');
process.exit(0);
}
}
main().catch(e => {
console.error(e);
process.exit(1);
});
package.json 脚本
{
"scripts": {
"build": "your build command",
"check:link": "node link-check.js"
}
}
CI 集成示例(GitCode CI)
stages:
- build
- check
build:
script:
- npm run build
link-check:
needs: [build]
script:
- npm run check:link
工程权衡
- 外部链接HEAD请求容易被CDN、反爬拦截,不建议强阻断外部链接,可以改成仅告警;
- 锚点校验是简单字符串匹配,复杂JS渲染生成的id无法识别,属于局限性;
- 自动修复只能处理路径层级、后缀大小写这类简单问题,复杂重构链接建议人工处理;
- 大站点扫描速度慢:可以增加缓存,只扫描本次commit变更的文件。
后续演进方向
- 支持页面内JS动态生成链接的捕获;
- 生成可视化死链报告页面;
- 自动提交PR修复可自动修正的链接;
- 和sitemap联动,只校验sitemap收录页面。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)