html不能直接被monorepo管理，必须作为构建产物存在；需将html所在子项目当作应用包用vite等工具构建，index.html为输出结果而非源码入口，所有引用须经构建流程处理，禁止硬编码路径或直接引用源码。
HTML 不能直接被 Monorepo 管理，必须作为构建产物存在
HTML 是静态标记语言，没有模块解析能力，也不认识 pnpm workspace 或 workspace:^ 这类协议。你无法在 index.html 里写 <script src="../packages/core/dist/index.js"></script> 并期望它在开发或生产中正常工作——路径会失效、类型不匹配、MIME 不支持、CI 构建失败。
真正可行的路径只有一条：把 HTML 所在的子项目（比如文档站、示例页、微前端子应用）当作一个「应用包」，用 Vite / esbuild / Webpack 构建，index.html 是构建输出结果，不是源码入口。
- 根目录不放裸
index.html，所有 HTML 必须由构建工具生成或注入 - 子包如
apps/docs的package.json必须声明"type": "module" -
vite.config.ts中需配置build.rollupOptions.output.manualChunks，避免 JS/CSS 路径硬编码 - 公共 HTML 片段（如头部、脚部）必须封装为可构建的包，例如
@demo/layout，导出模板字符串或 EJS 模板
如何让 HTML 安全引用 Monorepo 内部包
浏览器不支持 workspace: 协议，也不能直接加载 TypeScript 源码或未构建的 ESM 模块。开发和生产阶段的引用方式完全不同，混用必踩坑。
开发阶段靠 Vite 的 resolve.alias 实现源码直连：@demo/ui 映射到 ../../packages/ui/src，然后在 main.ts 里 import { Button } from '@demo/ui'，Vite Dev Server 自动处理；但 HTML 文件本身不直接 import，而是通过 <script type="module" src="/src/main.ts"></script> 加载入口。
生产阶段必须构建输出 UMD/ESM 格式文件，并复制进可部署路径：
- 运行
pnpm build在packages/ui输出dist/ui.umd.js和dist/style.css - 在
apps/docs的构建流程中，用插件或脚本将ui.umd.js复制到public/libs/ - HTML 中写
<script src="/libs/ui.umd.js"></script>，而非node_modules/...或相对路径 - 绝对禁止在 HTML 中写
../packages/xxx或./src/xxx.ts—— 这会让 CI 构建中断，也破坏包隔离
HTML 模板复用必须落地为可构建的包
想在多个子项目中复用头部导航、主题 CSS、SEO meta 模板？不能靠复制粘贴 HTML 文件，也不能靠构建时 cp 静态文件。必须把它变成一个可导入、可配置、可测试的包。
典型做法是新建 packages/templates，导出函数或模板字符串：
export function generateHtml({ title = 'Demo', theme = 'light' }) {
return `
<title>${title}</title>`;
}
然后在 apps/docs/vite.config.ts 中用 transformIndexHtml 插件调用该函数，动态生成 index.html。这样既复用了逻辑，又保留了每个子项目的定制能力。
- 模板包必须有明确的构建目标（如
dist/templates.cjs），供其他包require()或import - 不要在模板里硬编码路径，路径应由调用方传入（如
cssUrl、jsUrl） - 若需服务端渲染，模板包应同时提供 ESM + CJS 输出，并在
package.json中正确声明exports
常见错误：双击打开 index.html 就报错
这是最典型的本地调试误操作。浏览器直接打开 file:// 协议下的 index.html，根本不会触发构建流程，所有 import 语句都会因 MIME 类型错误而失败，fetch('/api') 也会跨域，@demo/ui 别名完全无效。
唯一合法的本地开发方式是启动 Vite Dev Server：pnpm --filter apps/docs dev，访问 http://localhost:5173。这个地址才能提供模块解析、HMR、代理、别名映射等全部能力。
- CI 构建时也必须执行
pnpm build，产出dist/目录，而不是直接上传源码中的index.html - GitHub Pages / Vercel / Netlify 部署的是
dist/下的内容，不是根目录或src/ - 如果非要快速预览 HTML，可用
npx serve -s dist，但不能替代vite dev
HTML 在 Monorepo 里从来不是“第一公民”，它是被构建出来的终端产物。它的复用性、可维护性和安全性，全系于构建流程是否规范、包边界是否清晰、引用路径是否可控——这些细节一旦松动，整个多包协作就退化成一堆散装文件。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
