结论：多仓库下公共html模板无法靠“复制粘贴”或“手动发布npm包”保持质量同步，必须用pnpm workspace+shared package+lint联动校验，否则每次改一个class名、删一个空格，都会在不同项目里产生不一致的渲染结果和可访问性问题。
直接说结论：多仓库下公共 HTML 模板无法靠“复制粘贴”或“手动发布 npm 包”保持质量同步，必须用 pnpm Workspace + shared package + lint 联动校验，否则每次改一个 class 名、删一个空格，都会在不同项目里产生不一致的渲染结果和可访问性问题。
为什么 HTML 模板在多仓库中极易失真
HTML 模板不像 JS 函数能被 import 复用，它常以字符串、文件片段或构建时 html-webpack-plugin 注入方式存在。一旦分散在多个仓库，就面临：
- 不同项目用不同版本的
prettier格式化，导致缩进、换行、属性顺序不一致 - 同一份模板在 site-a 里用
aria-label，site-b 里漏写，a11y 扫描工具报错不统一 - shared-lib 更新了按钮语义结构（如从
<div role="button"> 改为 <code><button></button>），但只有部分项目执行了pnpm run build:html - CI 流程里没校验 HTML 片段是否通过
html-validate，上线后才发现id重复或alt缺失
用 pnpm Workspace 统一托管 HTML 模板文件
把所有 HTML 模板（header.html、card-template.html、footer.html）放进 workspace 的 packages/shared-templates 目录，其他项目通过 file:../shared-templates 引用：
dependencies: {
"shared-templates": "file:../shared-templates"
}
关键点：
- 模板文件必须用
.html后缀，不能用.htm或.txt，否则html-validate插件无法识别 - 根目录
pnpm-workspace.yaml要显式包含该包：packages: ["packages/*", "packages/shared-templates"] - 禁止在子项目里再建同名
templates/目录——冲突根源往往来自“本地覆盖”
HTML 质量校验必须在 workspace 根目录统一运行
每个子项目自己跑 html-validate 会因配置路径、ignore 规则不一致而漏检。正确做法：
- 在
shared-templates的package.json里定义"scripts": { "lint:html": "html-validate --config ../../.htmlvalidate.json src/*.html" } - 根目录
.htmlvalidate.json配置全局规则，例如强制img[alt]、禁止内联style、要求lang属性 - CI 中只跑
pnpm -r --parallel lint:html，失败即阻断合并——别让 “模板没问题” 成为各项目自己的主观判断
注意：html-validate 默认不检查 data- 属性拼写，需手动加 rule："attr-name-style": ["error", "kebab-case"]，否则 data-userid 和 data-user-id 在不同项目里混用没人发现。
协同编辑 HTML 模板时的光标与 DOM 冲突要主动隔离
多人同时改 shared-templates/src/card-template.html，Git 冲突只是表象；更隐蔽的是：
- 开发者 A 在 VS Code 里用 Prettier 自动格式化，插入了换行；B 用 WebStorm，删掉了空格——Git 合并后变成
<div>\n <p>Text</p> </div>，但浏览器解析时换行可能转为空格，影响布局 - 模板里用了
contenteditable="true"的占位区域（如富文本编辑器预设内容），多人编辑时 DOM 快照 diff 会丢内容——必须禁用该属性，改用 JS 初始化时注入纯文本 - 所有模板里的
id必须带前缀（如tmpl-card-title），禁止用title这类通用名，否则嵌入到不同页面后 ID 冲突，document.getElementById()返回错节点
真正难的不是合并代码，而是确保 HTML 片段在任意项目、任意构建流程、任意浏览器中，输出的 DOM 结构和语义完全一致——这需要 lint、workspace、CI 三者咬合，缺一不可。
