From b22f3713c37f6e44c7524d95c437193cf8e8f3c0 Mon Sep 17 00:00:00 2001 From: wc24 Date: Fri, 14 Aug 2026 15:55:36 +0800 Subject: [PATCH] =?UTF-8?q?README:=20=E8=A1=A5=20optimizeDeps.include=20?= =?UTF-8?q?=E2=80=94=E2=80=94=20=E9=9B=B6=E6=A8=A1=E5=9D=97=E5=A3=B3?= =?UTF-8?q?=E6=97=B6=20element-plus=20=E4=BB=8E=E6=9C=AA=E8=A2=AB=E9=A2=84?= =?UTF-8?q?=E6=89=93=E5=8C=85=E4=BC=9A=E7=99=BD=E5=B1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 22 +++++++++++++++++++++- package.json | 2 +- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a0334f1..955a7df 100644 --- a/README.md +++ b/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、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。 diff --git a/package.json b/package.json index b42b090..5c11d24 100644 --- a/package.json +++ b/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",