构建面向生产环境的HTML模板组件化工程-html教程-PHP中文网

直接用标签无法上线生产，因其仅为静态占位符，不执行脚本、不加载资源、不触发事件；必须通过document.importnode(tmpl.content, true)克隆并手动挂载才能生效。

构建面向生产环境的html模板组件化工程

为什么直接用

它只是浏览器跳过的静态占位符，不执行脚本、不加载图片、不触发事件监听——你写好<template id="header"><header>...</header></template>，不配 JS 克隆插入，页面就永远空白。常见错误是把它当 Vue 的 <template></template> 用，结果构建完发现 header 没渲染、GA 脚本没加载、表单控件状态全丢。

真正能进生产的关键动作只有两个：document.importNode(tmpl.content, true) 克隆（不是 cloneNode()），再手动填充数据后挂载。否则所有“组件化”都是假象。

importNode 保留 <input checked> 状态、<select></select> 当前选项、Shadow DOM 兼容性；cloneNode(true) 在表单场景下会丢状态
模板内不能有 <script></script> 或 <style></style> —— 它们不会自动执行或生效，得靠 JS 动态注入或 adoptedStyleSheets
禁止硬编码 id="nav-1" 这类唯一标识，多次复用必然冲突；改用 data-component-id 或由工厂函数动态生成

Web Components 在生产环境的硬约束

Custom Elements 是目前唯一无需构建工具、零依赖、原生支持的组件方案，但浏览器不会替你兜底。注册失败、样式泄漏、属性不同步，全是开发时就能踩到的坑。

必须满足三条铁律才能稳定上线：

自定义标签名必须含短横线，比如 nav-bar 合法，navbar 直接被浏览器忽略
constructor 是唯一能调用 super() 和 this.attachShadow() 的地方；漏掉 super() 就报 Failed to construct 'customElements'
想让外部 CSS 生效，mode 得设为 'open'；设成 'closed' 后连 DevTools 都点不开 shadowRoot，调试成本翻倍

另外，observedAttributes 列表里拼错一个字母（比如写成 'Size' 而非 'size'），对应属性变化就完全静默——它不报错，只不工作。

Vite 构建中 HTML 模板如何注入环境变量

HTML 本身没有运行时环境概念，所谓“多环境”必须在构建阶段把变量 baked 进去。Vite 默认不处理 HTML 中的 %VITE_API_BASE% 这类写法，直接写进去只会原样输出。

Doc To HTML

使用 MinerU 文档处理引擎将 Word 文档（.doc、.docx）转换为保留结构和格式的干净 HTML。

下载

正确路径只有一条：用 vite-plugin-html 注入，而不是靠 JS 运行时读取。

在 vite.config.ts 中配置插件：html({ inject: { data: { VITE_API_BASE: import.meta.env.VITE_API_BASE } } })
HTML 模板里写 <script>const API_BASE = '<%= VITE_API_BASE %>'</script>，插件会在构建时替换为字符串字面量
别在 .env.development 里写 NODE_ENV=development —— Vite 只认 VITE_ 前缀，且 import.meta.env.NODE_ENV 是只读常量，不能覆盖

注意：Vite 不合并多个 .env 文件，.env.production 和 .env.staging 完全隔离，切 mode 时得确保对应文件存在且变量名一致。

纯 HTML 组件库上线前必须检查的三件事

没有框架兜底时，“能跑”和“能长期维护”之间差着十层 CSS 优先级和五个命名空间冲突。

上线前逐项核对：

所有类名带统一前缀，如 c-button、c-card__footer；禁用 .header、.modal 这类泛化名，否则 CDN 加个第三方 UI 库就炸
CSS 全部基于设计令牌，比如 padding: var(--c-space-md)；出现任何 8px、!important 或 px 单位，都意味着深色模式、高 DPR 屏幕、主题切换全部失效
每个组件 HTML 结构可独立复制粘贴进任意页面运行，不依赖外部 JS、不依赖全局 class、不依赖父级样式重置 —— 如果删掉 <link rel="stylesheet"> 就变形，说明封装失败