静态站点死链检测与自动修复实践

举报
yd_282816122 发表于 2026/11/17 23:13:52 2026/11/17
【摘要】 前言静态站点随着迭代、图片迁移、页面重构、文档改名,很容易产生大量死链:内部相对路径写错、锚点失效、外部第三方链接下线。人工逐页核对成本极高,放到CI中自动检测,发现问题直接阻断合并,是低成本保障站点可用性的方案。本文实现一套Node脚本,支持扫描HTML、Markdown内链接,区分内部链接/外部链接,支持自动修复简单路径错误,并输出报告。 痛点梳理人工巡检遗漏:锚点#section、相...

前言

静态站点随着迭代、图片迁移、页面重构、文档改名,很容易产生大量死链:内部相对路径写错、锚点失效、外部第三方链接下线。人工逐页核对成本极高,放到CI中自动检测,发现问题直接阻断合并,是低成本保障站点可用性的方案。本文实现一套Node脚本,支持扫描HTML、Markdown内链接,区分内部链接/外部链接,支持自动修复简单路径错误,并输出报告。

痛点梳理

  1. 人工巡检遗漏:锚点#section、相对路径../img/xxx.png改动后很难肉眼发现;
  2. 外部链接不可控:第三方文档、图床链接随时失效;
  3. 仅检测不阻断:发现死链但没有集成到流水线,问题持续堆积;
  4. 误报干扰:部分链接需要跳过校验(如动态埋点地址、管理后台链接)。

整体设计

  • 扫描范围:*.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

工程权衡

  1. 外部链接HEAD请求容易被CDN、反爬拦截,不建议强阻断外部链接,可以改成仅告警;
  2. 锚点校验是简单字符串匹配,复杂JS渲染生成的id无法识别,属于局限性;
  3. 自动修复只能处理路径层级、后缀大小写这类简单问题,复杂重构链接建议人工处理;
  4. 大站点扫描速度慢:可以增加缓存,只扫描本次commit变更的文件。

后续演进方向

  • 支持页面内JS动态生成链接的捕获;
  • 生成可视化死链报告页面;
  • 自动提交PR修复可自动修正的链接;
  • 和sitemap联动,只校验sitemap收录页面。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。