Guava UI 构建与部署常见问题
项目跑起来了但不知道怎么打包上线？构建后样式炸了？文件太大？ 这里汇总了构建和部署过程中最常碰到的问题，直接找你的场景。
构建产物相关
Q: 构建后的 style.css 体积太大了，正常吗？
这是正常的。 项目已对 Element Plus 做了按需引入（通过 docs/.vitepress/theme/element-plus-styles.ts），不是全量引入 element-plus/dist/index.css（约 350KB）。
当前优化情况
- CSS：Element Plus 已按需引入，guava-ui 全量样式暂无法按组件拆分
- JS：按需引入第三方库，避免全量引入
Q: 怎么进一步减小 JS 和 CSS 体积？
| 类型 | 当前状态 | 还能做什么 |
|---|---|---|
| CSS | Element Plus 已按需引入 | guava-ui 全量样式暂无法拆分 |
| JS | - | 第三方库必须按需引入，不要全量 import |
样式问题排查
Q: 开发环境样式正常，打包后样式全乱了怎么办？
按以下顺序排查：
- 是不是直接双击 HTML 打开的？ → 不能用
file://协议，必须通过 HTTP 访问 - 部署路径和
base配置是否一致？ → 检查env.ts里的VITE_BASE_PATH - 缓存没刷新？ → 浏览器强刷
Ctrl/Cmd + Shift + R
不要双击打开 HTML
生成的 dist/index.html 只能通过 HTTP Server 访问（Nginx、Vite Preview 等），不支持直接双击打开。
Q: 本地 dev 没问题，部署后样式丢失？
可能原因：
- 服务器没有配置 gzip / br 压缩
- CDN 缓存未刷新
- 部署路径和
base配置不匹配
部署相关问题
Q: 推荐的生产环境部署方式是什么？
bash
pnpm build然后将打包后的 dist 目录部署到服务器：
- 传统部署：放到 Web 服务器指定路径，如
/guava/ - 自动部署：配置 CI/CD 流水线
服务器必备配置
- 开启 gzip 压缩
- 开启 brotli (br) 压缩
- 静态资源配置长期缓存
Q: 部署到子路径（如 /guava/）需要注意什么？
需要修改 env.ts 中的配置：
typescript
VITE_BASE_PATH: '/guava/'; // 改成你实际的部署路径同时确保 Nginx 配置中 location 和 base 一致。