u

code/g3soft-libs/README.md

@@ -47,6 +47,39 @@ pnpm build:docs   # 构建文档站静态文件
 
 文档站静态产物在 `docs/.output/public`，可直接部署到任意静态托管。
 
+### 改完组件库，怎么让业务方生效
+
+`g3soft-erp` 通过 `overrides` link 到本仓库的 `packages/ui`，**消费的是构建产物 `dist/`**（`exports` 指向 `./dist/index.js` 与 `./dist/style.css`），不是源码。所以改了 `packages/ui/src` 之后不重新 build，业务方一点变化都看不到。
+
+关键在于**不能边跑 ERP dev server 边构建**。ERP 的 Vite 监视着 `dist/`，而 `vite build` 会先清空再逐个写回产物文件，于是：
+
+1. 每个产物文件被重写都触发一次 `page reload`，浏览器反复刷新；
+2. 构建中途 `dist/style.css` 会**短暂不存在**，而 ERP 的 `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.`
+
+还有更隐蔽的一种：server 没崩，但缓存到了**写入中途**的模块图，页面白屏、控制台报 `Failed to resolve import "./tooltip/Tooltip.js" from ".../dist/index.js"`。此时 `dist` 盘上的产物其实是完整的，问题纯粹在 Vite 缓存。
+
+**因此顺序只能是「先停、再构建、后启动」**：
+
+1. 停掉 ERP 的 dev server（占用 5090 端口）
+2. 在本仓库执行 `pnpm --filter @g3soft/ui build`
+3. 在 `g3soft-erp/web` 下执行 `pnpm dev` 重新启动
+
+若怀疑是缓存问题（白屏、找不到模块），额外删掉 `g3soft-erp/web/node_modules/.vite` 再启动即可。改 `packages/tokens` 同理 —— 它也要 build，且要在业务方 dev server 停掉时做。
+
+> 这跟 `pnpm dev`（文档站）无关：文档站通过 alias 直连 `packages/ui/src`，改源码即时热更，不需要也不应该为它重新构建组件库。
+
 ### 部署到子路径
 
 文档站支持挂载到子路径，构建时通过环境变量指定：