HTML本身不能做Monorepo管理，本质是将多个含index.html的子项目纳入统一仓库并由构建工具驱动；裸HTML文件无法被pnpm解析，import会报MIME错误，../packages路径在生产环境不存在，必须将HTML作为构建产物而非源码入口，所有公共资源需封装为可构建包并通过构建流程注入。
HTML 本身不能做 Monorepo 管理，所谓“HTML 大项目用 Monorepo”，本质是把多个含 index.html 的子项目（如文档站、示例页、静态应用）纳入统一仓库，靠构建工具驱动，而非靠 HTML 自身机制。
为什么直接放裸 HTML 文件进 packages/ 会失败
浏览器不解析 pnpm-workspace.yaml，也不理解 workspace:* 语义；双击打开 index.html 时，import 语句直接报 MIME 类型错误；../packages/ui/src 这类路径在生产环境根本不存在，CI 构建会中断。
- HTML 是产物，不是源码入口 —— 所有模板、组件、脚本必须先构建，再输出到
dist/index.html - 根目录禁止放任何裸
index.html，否则破坏 workspace 隔离边界 -
packages/下只能放可构建、可导出的包（如导出dist/template.js），不能放直接被浏览器加载的 HTML
如何组织含 HTML 的子项目（apps/ 目录）
每个子项目必须是完整可构建的应用，比如 apps/docs 或 apps/demo，它们用 Vite / esbuild 驱动，最终产出带 index.html 的 dist/ 目录。
-
package.json中必须声明"type": "module"，否则import无法工作 -
vite.config.ts要配build.rollupOptions.output.manualChunks，避免 JS/CSS 路径硬编码（如/assets/index.abc123.js） - 所有公共资源（如公共头部、脚部模板）应抽成独立包（如
@myorg/templates），通过import加载，而非fetch('./header.html') - 开发时用 Vite 的
resolve.alias映射@myorg/ui到../../packages/ui/src；生产时由构建流程自动 copy 到public/libs/并用绝对路径引用
HTML 页面怎么安全引用内部包（不崩、不报错）
浏览器不支持 node_modules/@myorg/core/index.js 这种路径写法，也不能在 <script src> 里写相对路径指向 ../packages/ —— 这些在 CI 和部署后全失效。
立即学习“前端免费学习笔记（深入）”；
- 开发阶段：Vite Dev Server 自动处理模块解析，HTML 里写
<script type="module" src="/src/main.ts">即可 - 生产阶段：必须构建。例如
packages/core运行tsc --declaration+rollup输出dist/core.umd.js，再让apps/demo的构建脚本把它复制进public/libs/ - HTML 中引用固定路径：
<script src="/libs/core.umd.js">，不要用import动态加载未构建的源码 - 禁用所有
../packages/xxx、file://、./src/类路径 —— 它们只在本地开发时“看起来能跑”，上线即断
WebStorm / VS Code 怎么正确识别 HTML 子项目里的跨包跳转
IDE 默认不识别 workspace 结构，导致 Ctrl+Click 跳不到 @myorg/ui 的源码，类型提示也失效。
- 必须打开整个仓库根目录（不是只开
apps/demo文件夹） - 确认根目录有合法
pnpm-workspace.yaml或package.json#workspaces字段 - 根目录
tsconfig.json设"composite": true和"references"，每个子包自己的tsconfig.json也要设"composite": true - 启用
baseUrl+paths映射，并在 IDE 设置里勾选 “Use path mappings from tsconfig.json” - 删过
node_modules后，务必先pnpm install再重启 IDE —— 否则.pnpm软链接缺失，路径映射直接失效
真正难的不是配置 workspace，而是让每个 HTML 子项目彻底放弃“直接编辑 index.html”的惯性思维——它必须成为构建产物的一部分，而不是起点。
