HTMLProofer必须在构建镜像时运行，因为生产镜像的HTML文件固化于只读层，发布后无法修复链接失效、图片404或标签错误；且默认仅打印警告不中断CI流程，须显式配置--fail_level=error才能阻断问题镜像推送。
为什么 htmlproofer 必须在构建镜像时运行，而不是发布后？
因为生产镜像一旦打包完成，HTML 文件就固化在只读层里，后续无法修复链接失效、图片 404 或标签嵌套错误。漏刷的 HTML 问题会直接暴露给用户，且 CI 流程中若跳过这步，htmlproofer 的输出结果根本不会触发构建失败 —— 它默认只打印警告，不中断流程。
常见错误现象：htmlproofer 在本地跑出 12 个 broken link，但 CI 日志里只显示 “Finished with warnings”，镜像照常推送。根本原因是没加 --fail_level 参数。
- 必须显式设置
--fail_level=none（全通过）、warn（警告不失败）或error（任一错误即退出） - 推荐在生产构建中固定用
--fail_level=error，否则等于没查 - 注意：
htmlproofer默认检查href和src，但不会验证内联style中的 URL，这类需额外配置--url-ignore或自定义 check
Dockerfile 中嵌入 htmlproofer 的安全写法
不能直接 RUN gem install html-proofer && htmlproofer /app/build —— 这会让 Ruby 环境和依赖混进最终镜像，增大攻击面，且 Ruby 版本不锁定易导致非确定性失败。
正确做法是用多阶段构建，把验证逻辑隔离在 builder 阶段：
立即学习“前端免费学习笔记（深入）”；
FROM ruby:3.2-slim AS html-checker RUN gem install html-proofer --version '>=4.0' WORKDIR /app COPY ./build/ . RUN htmlproofer . --check-html --check-favicon --url-ignore "/google-analytics.com/,/#/" --fail_level=error FROM nginx:1.25-alpine COPY --from=html-checker /app/ /usr/share/nginx/html/
关键点：
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
- builder 阶段用
ruby:3.2-slim而非latest，避免因 Ruby 小版本升级导致html-proofer行为变更 -
--check-favicon必开：很多 favicon.ico 路径写错，但浏览器静默忽略，htmlproofer默认不查它 -
--url-ignore里填的是正则，不是 glob；/#要写成/\#/，否则报错
静态资源路径错位导致 htmlproofer 误报的典型场景
当你的 HTML 是由 Jekyll/Hugo 构建，而 htmlproofer 直接扫生成目录时，容易出现 “文件存在但被报 404” —— 实际是 baseurl 或 permalink 配置让真实路径和文件系统路径不一致。
比如 Hugo 生成的 /blog/post-1/index.html，实际访问路径是 /blog/post-1/，但 htmlproofer 默认按文件路径校验，会去请求 /blog/post-1/index.html（正确），还是 /blog/post-1/（可能重定向）？它取决于服务器配置。
- 解决方案：用
--assume-extension让它把/blog/post-1/当作/blog/post-1/index.html处理 - 更稳妥的做法是配合 Nginx 镜像，在 builder 阶段起一个临时 server，用
--url-swap把本地路径映射成可访问 URL - 注意：
--url-swap的格式是"old_regex:new_url"，例如"^/":"http://localhost:8080/"，必须带协议和端口
CI 中如何避免 htmlproofer 成为瓶颈？
全量扫描几百个 HTML 文件可能耗时 2–3 分钟，尤其在 GitHub Actions 默认 2 核 CPU 上。这不是工具慢，而是默认并发数太低（htmlproofer 默认单线程）。
提速关键不是换工具，而是调参：
- 加
--only_4xx：跳过 3xx 重定向检查，省掉大量 HTTP 请求 - 用
--typhoeus-config '{"max_concurrent": 10}'提高并发连接数（需确保目标站点允许） - 对大型站点，拆分检查：先用
--file_extensions=".html"锁定范围，再排除--ignore "/admin/,/drafts/" - 注意：
--typhoeus-config是 JSON 字符串，双引号必须转义，否则 shell 解析失败
真正容易被忽略的点是：你设了 --timeout 5，但某些 CDN 图片响应慢于 5 秒，htmlproofer 就直接标为 404 —— 这不是链接坏了，是超时策略太激进。建议生产环境设 --timeout 15 并配 --retry-count 2。
