跨产品线HTML/CSS组件模板同步更新管道设计

跨产品线同步 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 产品还没跟上时，怎么让两者还能共存。这要求每个模板文件都自带兼容性声明，而不是指望靠人肉对齐来解决问题。