跨产品线同步 HTML/CSS 组件模板，这事儿说起来简单，做起来全是坑。不少人第一反应就是：把 header.html 或者 _button.css 手动拷过去，改两行代码就完事。结果呢？A 产品线加了 data-variant="ghost"，B 产品线完全没感知；C 产品线升级了 Bootstrap，CSS 变量名从 --bs-primary 换成了 --primary-color，但 A、B 那边的样式还赖在旧变量上，一上线就崩。问题的根源并不在“同步不及时”这个表象上，而是整个流程里缺少了版本锚点和变更感知机制。
为什么直接复制粘贴模板会失效
根本原因其实很清楚：模板本身不携带版本信息，更不会告诉下游它依赖什么。A 产品的代码改了结构，B 产品对此一无所知。这就好比两个人对暗号，但暗号本子从来不更新——不出乱子才怪。
必须用构建时注入的语义化版本号控制模板输出
HTML 和 CSS 模板本身不带着版本号跑，但它们的消费方能注入。关键不在于文件名里带个 v2.1.0，而在于每次构建出来的产物，必须明确声明它依赖哪一套组件契约。
- 在 Webpack 或 Vite 的构建配置里，通过
DefinePlugin或define注入一个全局常量，比如__COMPONENT_VERSION__ = '2.1.0'。 - HTML 模板里用
这种注释，或者在标签上加一个data-component-version="2.1.0"。 - CSS 文件末尾追加
/* version: 2.1.0 */的注释，让 CI 脚本可以直接比对。 - 这里特别强调一下，别用 Git commit hash 来替代语义化版本——
abc1234这种字符串，既看不出是不是 breaking change，也不方便人工排查，等于没加。
CSS 变量与 HTML 结构需双向契约校验
光靠版本号也不够。A 产品用了新结构 ，但 B 产品的 CSS 里还在认 .btn-large，运行时直接挂。必须有一套可执行的契约验证机制。
- 用
playwright启动个真实浏览器，加载各产品线的组件 demo 页面，检查getComputedStyle(el).getPropertyValue('--btn-padding-y')是否非空。 - 用
html-validate扫描所有 HTML 模板，确保每一个data-*属性都在component-contract.json里登记过，没登记的直接报错。 - CSS 里所有
var(--*)的使用，必须能在tokens.json里找到对应项，缺失的用stylelint插件stylelint-custom-property-no-unused拦截下来。 - 绝不可以在 CSS 里写
color: #3B82F6这类硬编码值——它绕过了契约，等于给同步管道埋了颗定时冲击波。
更新失败时 fallback 到上一版模板的兜底策略
CI 流水线里某个产品线构建失败，不能把整个同步流程卡住。要允许它“局部降级”，而不是全链路阻塞。
- 所有模板资源统一托管在私有 CDN 上，路径里带版本号，比如
https://cdn.example.com/templates/v2.1.0/header.html。 - 前端加载时用
fetch()带failover逻辑：先尝试 v2.1.0，如果 404 就自动回退到 v2.0.0，再 404 才真的报错。 - SSR 服务启动时，把多个模板版本预加载到内存里，避免运行时网络抖动导致降级失败。
- 监控必须捕获降级事件——每发生一次
v2.1.0 → v2.0.0的回退，立即告警，并且标记该产品线为“同步异常”状态。
说到底，最难的不是怎么推新模板，而是当 A 产品改了结构、B 产品还没跟上时，怎么让两者还能共存。这要求每个模板文件都自带兼容性声明，而不是指望靠人肉对齐来解决问题。
