组件库项目打包（排错&项目依赖升级&PWA）
概述
本节介绍组件库项目的打包发布流程，包括生产环境预览测试、依赖升级、PWA 集成以及常见打包错误的排查。
打包与预览
构建命令
# 仅构建（不检查类型）
pnpm build-only
# 构建后预览
pnpm preview
# 组合执行（推荐）
pnpm build-only && pnpm preview
bash
使用 npm-run-all 并行/串行执行
// package.json
{
"scripts": {
"build-only": "vite build",
"preview": "vite preview",
"p": "run-p build-only preview",
"p:series": "run-s build-only preview"
}
}
json
| 命令 | 说明 |
|---|---|
run-p (parallel) | 并行执行多个脚本 |
run-s (series) | 串行执行多个脚本 |
npm run p | 并行构建和预览 |
打包体积分析
Vite 构建时会输出每个 chunk 的体积信息：
dist/index.html 0.45 kB
dist/assets/index-3f2a1b.js 245.68 kB │ gzip: 78.32 kB
dist/assets/index-a1b2c3.css 120.45 kB │ gzip: 35.12 kB
text
- 黄色警告：chunk 超过 500KB，建议代码分割
- 红色警告：chunk 超过 1000KB，必须优化
优化方向
| 问题 | 解决方案 |
|---|---|
| 单个 JS 文件过大 | 动态 import + 代码分割 |
| 第三方库体积大 | CDN 外部化（vite-plugin-cdn2） |
| 不必要的 locale 打包 | external 排除 locale 文件 |
| CSS 体积大 | CSS 压缩、提取公共样式 |
| 图片未压缩 | imagemin 或图片 CDN |
依赖升级
# 查看过时的依赖
pnpm outdated
# 交互式升级
pnpm update -i
# 升级到最新版本（包括主版本）
npx pnpm-upgrade
bash
升级注意事项
| 事项 | 说明 |
|---|---|
| 破坏性变更 | 查看 CHANGELOG 和 Migration Guide |
| peerDependencies | 确保与项目其他依赖兼容 |
| 锁文件 | 升级后重新生成 pnpm-lock.yaml |
| 测试 | 升级后全量回归测试 |
PWA 集成
安装 PWA 插件
pnpm add -D vite-plugin-pwa
bash
配置
// vite.config.ts
import { VitePWA } from 'vite-plugin-pwa'
export default defineConfig({
plugins: [
vue(),
VitePWA({
registerType: 'autoUpdate',
includeAssets: ['favicon.ico', 'apple-touch-icon.png'],
manifest: {
name: 'My Admin App',
short_name: 'Admin',
description: 'Admin Dashboard',
theme_color: '#409eff',
icons: [
{
src: 'pwa-192x192.png',
sizes: '192x192',
type: 'image/png'
},
{
src: 'pwa-512x512.png',
sizes: '512x512',
type: 'image/png'
}
]
},
workbox: {
globPatterns: ['**/*.{js,css,html,ico,png,svg}'],
runtimeCaching: [
{
urlPattern: /^https:\/\/api\./i,
handler: 'NetworkFirst',
options: {
cacheName: 'api-cache',
expiration: { maxEntries: 100, maxAgeSeconds: 60 * 60 }
}
}
]
}
})
]
})
typescript
打包排查清单
| 检查项 | 说明 |
|---|---|
| 构建是否成功 | pnpm build-only 无错误 |
| 页面是否正常 | 所有路由页面可访问 |
| 功能是否完整 | 表单、表格、图表等组件正常 |
| 静态资源是否加载 | 图片、图标、字体加载正常 |
| API 请求是否正常 | 生产环境代理配置正确 |
实践要点
- 先
build-only构建，再preview本地预览，全量测试所有页面 - 使用
run-p并行执行构建和预览脚本 - 升级依赖前查看 CHANGELOG，升级后全量回归测试
- PWA 配置需提供 manifest 和图标文件，支持离线缓存
- 注意构建输出中的体积警告，及时进行代码分割和 CDN 优化
↑