u

code/g3soft-erp/README.md

@@ -74,6 +74,41 @@ overrides:
 2. **`vite.config.ts` 必须保留 `dedupe: ['vue', ...]`**。link 进来的包会带自己的 Vue 副本，不去重会导致组件内响应式失效（组件内部 ref 变化不触发外部渲染）——link 方案最经典的坑。
 3. **CI / 其他机器**：相对路径依赖目录层级。私库就绪后应把开发期 `link:` 换成私库版本号。
 
+### 本地联调组件库：构建时必须先停掉 dev server
+
+上面那条「改完组件库必须重新 build」还差半句：**构建组件库时要先停掉本项目的 dev server**。
+
+原因是 Vite 监视着 link 进来的 `packages/ui/dist/`，而 `vite build` 会先清空再逐个写回产物文件，于是：
+
+1. 每个产物文件被重写都触发一次 `page reload`，浏览器反复刷新；
+2. 构建中途 `dist/style.css` 会**短暂不存在**，而 `src/styles/index.scss` 里有 `@use '@g3soft/ui/style.css';`，Sass 解析时文件已经没了 —— dev server 进程直接崩溃：
+
+```
+[vite] Internal server error: [sass] ENOENT: no such file or directory,
+  open 'D:\workspace\code\g3soft-libs\packages\ui\dist\style.css'
+  ╷
+9 │ @use '@g3soft/ui/style.css';
+  │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  ╵
+  src\styles\index.scss 9:1  root stylesheet
+```
+
+随后是 `ELIFECYCLE Command failed with exit code 4294967295.`
+
+3. 还有一种更隐蔽的：server 没崩，但缓存到了**写入中途**的模块图，页面白屏、控制台报 `Failed to resolve import "./tooltip/Tooltip.js" from ".../dist/index.js"`。此时磁盘上的 `dist` 其实是完整的，问题纯粹在 Vite 缓存。
+
+**正确顺序**：
+
+```bash
+# 1) 停掉本项目 dev server（占用 5090 端口）
+# 2) 构建组件库
+cd ../g3soft-libs && pnpm --filter @g3soft/ui build
+# 3) 重新启动
+cd ../g3soft-erp/web && pnpm dev
+```
+
+若怀疑是缓存问题（白屏、找不到模块），在启动前额外删掉 `web/node_modules/.vite` 再 `pnpm dev`。改 `@g3soft/tokens` 同理（`pnpm --filter @g3soft/tokens build`），也要在 dev server 停掉时做。
+
 ### 想要组件库热更新？
 
 `link:` 指向**已构建的 `dist/`**，改源码不会即时生效。若要像 `g3soft-libs/docs` 那样直连源码，在 `vite.config.ts` 里加 alias：