Monorepo架构下多子应用HTML代码质量的一致性校验-html教程-PHP中文网

html eslint 能跨子应用统一配置，但必须置于 monorepo 根目录并适配多包路径结构；需显式启用 eslint-plugin-html、按子包隔离 lint-staged 规则、分层处理纯 html 与框架内模板，且 ci 中应仅检查变更文件并禁用自动修复。

monorepo架构下多子应用html代码质量的一致性校验

HTML ESLint 能否跨子应用统一配置

能，但必须放在 Monorepo 根目录，且配置需适配多包路径结构。根目录的 .eslintrc.js 或 eslint.config.js 会被所有子包继承，前提是每个子应用的构建/开发命令（如 vite dev、webpack serve）都启用 ESLint 插件并加载根配置。

常见错误是：在 packages/app-web/.eslintrc.js 中单独写一套规则，导致和 packages/app-admin 不一致；或者没在子包的 package.json 中声明 "eslintConfig": { "extends": "../../.eslintrc.js" }，造成配置未生效。

推荐用 eslint.config.js（ESLint v8.22+）替代旧版 JSON/JS 配置，支持导出函数式配置，可动态判断当前包类型
HTML 文件默认不被 ESLint 处理，必须显式启用 eslint-plugin-html 并在 files 中包含 **/*.html
若子应用使用不同框架（React/Vue），需在 overrides 中按路径区分规则，例如对 packages/app-vue/**/*.html 关闭 JSX 相关检查

如何避免 HTML 检查误报或漏报

Monorepo 中 HTML 文件常嵌入框架模板（如 Vue SFC 的 <template></template>、React 的 JSX 字符串），原生 HTML ESLint 无法解析这些上下文，直接扫描会大量误报。

正确做法是分层处理：

Markdown to HTML

{"answer":"将 Markdown 转换为内嵌 CSS、样式精美的独立 HTML。完美适用于新闻简报、文档、报告及邮件模板。"}

下载

对纯静态 HTML（如 public/index.html、营销页 packages/landing/*.html）直接用 eslint-plugin-html + html-validate
对框架内模板，交给对应插件：Vue 用 eslint-plugin-vue 检查 <template></template>，React 用 eslint-plugin-react 检查 JSX 中的 HTML 结构
禁用全局 HTML ESLint 对 src/**/*.{vue,tsx} 的扫描，否则和框架插件冲突
通过 lint-staged 绑定到 git hook，只检查本次提交变更的 HTML 文件，避免全量扫描拖慢 pre-commit

lint-staged 在多子应用中如何精准触发

不能只靠根目录一个 .lintstagedrc.js，否则改 packages/ui-components 的 HTML 也会触发 packages/app-mobile 的检查——既低效又可能失败（因为 app-mobile 可能没装 HTML 检查依赖）。

必须按子包边界隔离 lint 规则：

每个子包的 package.json 中定义独立脚本，例如："lint:html": "eslint --ext .html src/index.html"

lint-staged 配置按包路径过滤：

module.exports = {
  'packages/*/src/index.html': 'npm run lint:html',
  'packages/*/public/*.html': 'html-validate'
};

确保各子包 devDependencies 中包含所需插件（如 eslint-plugin-html），而非仅根目录安装——pnpm/npm workspaces 不自动 hoist 插件到子包 node_modules
若用 Turborepo，可在 turbo.json 中为 lint 任务配置 pipeline.lint.dependsOn，让 HTML 检查只运行在含 HTML 文件的包上

CI 流水线里 HTML 质量卡点怎么设才不拖慢构建

HTML 检查不是越严越好，而是要卡住真实风险点：缺失 <title></title>、未闭合标签导致渲染异常、XSS 风险属性（如 v-html）滥用。全量扫描所有 HTML 文件在 CI 中会显著延长耗时。

只对 git diff 输出的变更 HTML 文件执行检查，命令示例：git diff --name-only HEAD~1 | grep '\.html$' | xargs eslint
把 HTML 检查拆成两个阶段：pre-build 阶段做轻量校验（doctype、charset、基础语义），build 后阶段做深度校验（可访问性 ARIA、SEO 标签）
对 public/ 下的 HTML 启用缓存，只要文件未变就跳过检查；对生成的 HTML（如 Vite 构建产物）用 html-validate 做最终快照比对
禁止在 CI 中启用 --fix 自动修复，HTML 自动修复容易破坏模板逻辑，应只报告问题并阻断 PR

最易被忽略的是：HTML 检查工具本身依赖 Node 版本和解析器选项，不同子应用若用不同构建工具（Vite/Webpack/Rspack），其 HTML 加载方式不同，必须在各自构建配置中显式传入相同 parser 选项，否则同一份 HTML 在本地和 CI 中检查结果可能不一致。