README: 补 optimizeDeps.include —— 零模块壳时 element-plus 从未被预打包会白屏

README.md

@@ -54,6 +54,11 @@ export default defineConfig({
     optimizeDeps: {
         // ⚠️ 不能删 —— 删了整页白屏,报 resolveVue: components/layout.vue not found in sources
         exclude: ['shrimp-admin'],
+        // ⚠️ 也不能删 —— 上面这行让 vite 的依赖扫描停在本包门口,看不见本包 import 的
+        // element-plus / xlsx。消费侧 src/ 下如果没有自己的业务 .vue 顺手 import 到它们,
+        // 它们就一次都没被预打包,内部的 CJS 依赖(dayjs)原样送进浏览器 → 整页白屏,
+        // 控制台只有一行 does not provide an export named 'default'。列的就是下面那份 peer 清单
+        include: ['vue', 'vue-router', 'vue-i18n', 'axios', 'element-plus', '@element-plus/icons-vue', 'xlsx'],
     },
     resolve: {
         // ⚠️ 不能删 —— 删了 element-plus 与 shrimp-admin 各带一份 vue/dayjs,互操作错位
@@ -131,7 +136,8 @@ import { ShrimpTable } from 'shrimp-admin'
 | `Failed to resolve import "xlsx"`,vite 起不来 | 少装 peerDependency `xlsx` | `npm i xlsx`,模板第 1 节 |
 | 页面出来了但没样式,**图标巨大** | 没引 element-plus 基础样式 | main.ts 加两行 css,模板第 3 节 |
 | 能登录、菜单也有,但**所有列表都 404** | 服务端装的是 Express 4 | 服务端升到 `express@^5` |
-| `does not provide an export named 'default'`(dayjs / element-plus) | 依赖被装了两份 | vite.config `resolve.dedupe`,模板第 2 节 |
+| `does not provide an export named 'default'`(dayjs),整页白屏 | element-plus 从没被预打包过,它的 CJS 依赖被原样送进浏览器 | vite.config `optimizeDeps.include`,模板第 2 节 |
+| `does not provide an export named 'default'`(其他包) | 依赖被装了两份 | vite.config `resolve.dedupe`,模板第 2 节 |
 
 ## 验收: 必须在浏览器里打开页面
 
@@ -149,6 +155,20 @@ Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `nod
 - 框架的内置组件表靠 `import.meta.glob('./{components,module}/**/*.vue')` 收集,这是 **Vite 编译期宏**,esbuild 不认识,会原样抄进产物;等它在 `.vite/deps/` 目录下才被展开时,那个目录里一个 `.vue` 都没有 → 内置表变成空对象 `{}` → 内置兜底全部落空。
 - 预打包等于复制出第二份模块实例,`vueAdmin` 单例会分裂成两个,消费侧拿到的和框架内部用的不是同一个。
 
+## `optimizeDeps.include: [...]`
+
+上面那条 `exclude` 的代价:vite 的依赖扫描从 `index.html` 顺着消费侧的源码走,走到 `shrimp-admin` 就停了 —— 被 exclude 的包不进扫描,所以**框架 import 了什么,vite 一无所知**。
+
+以前这不出事:消费侧总要写几个业务模块 `.vue`,里面顺手 `import { ElMessage } from 'element-plus'`,扫描器照样摸得到。而从 v0.8.4 起模块壳可以一个都不写(见「业务模块」一节),于是完全可能出现**消费侧 `src/` 里没有任何一处 import element-plus** —— 它整包从未被预打包,所有 `element-plus/es/**` 被原样送给浏览器,其中的 `import dayjs from 'dayjs'` 指向一个 CJS 文件,当场炸:
+
+    The requested module '/node_modules/dayjs/dayjs.min.js' does not provide an export named 'default'
+
+整页白屏,控制台就这一行,`vite build`(rollup)一路绿灯。
+
+**不要顺着报错一个个补 `dayjs`、`dayjs/plugin/customParseFormat`……** 那是在追症状,换个 element-plus 版本要重列一遍。**也不要用 `optimizeDeps.entries` 指向 `node_modules/shrimp-admin/src/**`** —— 扫描器不认 node_modules 里的入口 glob,实测加了等于没加(`.vite/deps/_metadata.json` 里仍然只有 `vue`)。
+
+正确的做法是把本包用到的运行时依赖点名列出,那份清单就是下面 peerDependencies 本身 —— 消费侧本来就得装它们,这里只是再说一句「请预打包」。
+
 ## element-plus 的两行 css
 
 `shrimp-admin/style` 只包含框架自己的覆盖样式与暗色变量(`fix.scss` / `dark.scss` 等),**不含** element-plus 本体的样式表。element-plus 是 peerDependency、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。

package.json

@@ -1,6 +1,6 @@
 {
     "name": "shrimp-admin",
-    "version": "0.8.4",
+    "version": "0.8.5",
     "private": true,
     "description": "Shrimp 框架前端 — 消费 ShrimpServer + ShrimpTable 契约的经典 Vue3 + Element Plus 实现",
     "main": "src/index.ts",