前端HTML持续集成环境下的调试方法-html教程-PHP中文网

HTML检查CI失败而本地正常，主因是路径、工作目录或输出格式不一致；需配置htmlhint格式化、校验glob路径、确保.codequality.json路径正确且声明artifacts，axe-core须配合Puppeteer/Playwright执行。

前端html持续集成环境下的调试方法

GitLab CI 或 GitHub Actions 里 HTML 检查失败但本地跑得通？八成是路径、工作目录或输出格式没对上，不是代码本身有问题。

htmlhint 报错不显示具体行号

默认 htmlhint 输出是人类可读文本，CI 流水线无法提取位置信息。GitLab / GitHub 不会把这种输出当「问题」处理，MR 里自然看不到高亮红线。

必须加 --format=compact（GitHub Actions）或 --format=codeclimate（GitLab CI），否则连基础定位都做不到
确保 glob 表达式不扫 node_modules 或 .git，例如用 src/**/*.html 而非 **/*.html
如果用了 .htmlhintrc，确认它在 CI 工作目录下（$CI_PROJECT_DIR 或 $GITHUB_WORKSPACE）且未被 ignore 规则跳过

codequality.json 生成了但 MR 里没标记

文件存在 ≠ GitLab 能解析。常见卡点是路径字段不对或 artifact 声明缺失。

codequality.json 中每个 issue 的 location.path 必须是相对路径（如 src/index.html），不能带 ./ 前缀，更不能是 /builds/group/project/src/index.html 这类绝对路径
CI job 里必须显式写 artifacts: [codequality.json] 且设 expire_in: 1 week，否则文件一小时后就被删，MR 页面加载时已失效
code_quality: codequality.json 是顶级 key，不能缩进在 script: 下面，否则 GitLab 直接忽略

axe-core 检查没报错但实际页面可访问性差

axe-core 静态扫描几乎没用——它需要真实 DOM 渲染环境才能判断 aria-* 是否生效、tabindex 是否冲突、屏幕阅读器能否读到内容。

DeepBI DHTML 页面生成器

生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur

下载

必须配合 Puppeteer 或 Playwright 启动无头浏览器，例如用 npx axe-playwright --ci src/index.html
别指望只跑 axe-core npm 包：它只是库，不带执行环境；CI 里直接 require('axe-core') 会因缺少 window 报错
检查是否漏掉 await axe.run() 或等价的异步调用；返回空结果不等于通过，可能是脚本没执行完就退出了

本地能过、CI 失败的隐藏原因

最常被忽略的是工作目录和依赖版本不一致，尤其当项目含自定义构建步骤时。

CI 默认工作目录未必是项目根目录，加 before_script: cd $CI_PROJECT_DIR（GitLab）或 run: cd $GITHUB_WORKSPACE（GitHub）强制锚定
不要省略 npm ci，用 package-lock.json 锁死 htmlhint 版本；不同 minor 版本对 attr-no-duplication 等规则的触发逻辑可能变化
如果 HTML 是构建产物（如 Vite 打包后的 dist/index.html），确保 CI 先执行 npm run build 再 lint，否则扫描的是源码模板而非最终 HTML