Vue 项目 package.json 终极详解（主流实践 / 逐项说明）

文章目录

- [一、package.json 完整示例](#一、package.json 完整示例)
- 二、字段逐项详解（用途、取值、坑位）
- - 2.1、元信息
  - 2.2、运行环境与包管理
  - 2.3、脚本（scripts）
  - 2.4、依赖分类
  - 2.5、代码质量与提交流程
  - 2.6、目标浏览器
  - 2.7、依赖覆盖/强制解析
  - [2.8、发布与 Tree Shaking](#2.8、发布与 Tree Shaking)
  - 2.9、法务与追踪
  - 2.10、运行时版本固定（可选）
- 三、脚本常见扩展（可按需添加）
- 四、依赖清单说明（为何选它们）
- 五、版本前缀策略（避免"隐性升级"翻车）
- 六、变体与可选字段
- - [6.1、使用 pnpm 的覆盖写法](#6.1、使用 pnpm 的覆盖写法)
  - [6.2、仅 JavaScript 项目（去掉 TS 相关）](#6.2、仅 JavaScript 项目（去掉 TS 相关）)
  - [6.3、 Monorepo（工作空间）](#6.3、 Monorepo（工作空间）)
  - [6.4、发布型库与应用的区别](#6.4、发布型库与应用的区别)
  - [6.5、浏览器兼容更精细](#6.5、浏览器兼容更精细)
- [七、落地建议（CI/CD & 团队）](#七、落地建议（CI/CD & 团队）)
- 八、常见报错与排查

面向 Vue3 + Vite 技术栈，附完整示例与每个字段的用途、取值建议、易踩坑位。示例采用 TypeScript + Pinia + Vue Router + Vitest + ESLint + Prettier + Husky + Lint-Staged，并固定包管理器为 pnpm（可切换为 npm/yarn）。

一、package.json 完整示例

一个主流的 package.json 完整示例（可直接用）

powershell 复制代码

{
"typescript": "~5.4.0",
"vue-tsc": "^2.0.29",


"vitest": "^2.0.5",
"@vitest/coverage-v8": "^2.0.5",


"eslint": "^9.8.0",
"@eslint/js": "^9.8.0",
"eslint-plugin-vue": "^9.26.0",
"@typescript-eslint/parser": "^8.0.0",
"@typescript-eslint/eslint-plugin": "^8.0.0",
"prettier": "^3.3.3",
"eslint-config-prettier": "^9.1.0",


"lint-staged": "^15.2.8",
"husky": "^9.1.4",
"cross-env": "^7.0.3",


"rollup-plugin-visualizer": "^5.12.0",
"vite-plugin-inspect": "^0.8.0",


"postcss": "^8.4.41",
"autoprefixer": "^10.4.20",
"tailwindcss": "^3.4.10"
},


"lint-staged": {
"*.{ts,tsx,vue,js}": ["eslint --fix", "prettier --write"],
"*.{css,scss,md,json}": ["prettier --write"]
},


"browserslist": [
"last 2 versions",
"> 1%",
"not dead",
"not op_mini all"
],


"overrides": {
"minimatch": "^9.0.4"
},
"resolutions": {
"glob-parent": "~6.0.2"
},


"publishConfig": {
"access": "public"
},
"sideEffects": false,


"author": "Your Name <you@example.com>",
"license": "UNLICENSED",
"repository": {
"type": "git",
"url": "git+https://github.com/yourorg/acme-vue-app.git"
},
"bugs": {
"url": "https://github.com/yourorg/acme-vue-app/issues"
},
"homepage": "https://github.com/yourorg/acme-vue-app#readme",


"volta": {
"node": "20.16.0",
"pnpm": "9.6.0"
}
}

说明：以上 JSON 合法且可直接使用。其中 overrides（npm）与 resolutions（yarn）二者并存仅为演示，实际项目按所用包管理器择一；pnpm 推荐使用 pnpm.overrides（见下文"变体"）。

二、字段逐项详解（用途、取值、坑位）

2.1、元信息

name：包名/应用名（npm 规则：小写、连字符）。私有应用也建议规范命名，利于 CI 与制品追踪。
version：语义化版本（MAJOR.MINOR.PATCH）。应用可以不频繁改，但发版/制品追踪建议维护。
private：为 true 时禁止被 npm publish 误发布，强烈建议应用项目开启。
description / keywords：用于人类/搜索，CI 报表、文档站点也会用到。

2.2、运行环境与包管理

packageManager：锁定包管理器与版本（如 pnpm@9.6.0），避免团队环境差异。
type："module" 表示 Node 端默认使用 ESM；配合 Vite/现代前端更一致。若使用 CJS，改为省略或显式 "commonjs"。
engines：声明 Node/包管理器版本范围，CI/CD 可据此拒绝不兼容环境。

例："node": ">=18.18 <23" 兼顾 LTS 与 Vite 5 要求。

2.3、脚本（scripts）

dev：本地开发启动 Vite 开发服务器。
build：执行生产构建，输出到 dist/。
preview：本地预览生产构建产物；--strictPort 避免自动换端口导致脚本监控混乱。
type-check：仅做 TS 类型检查，不产出文件；在 CI 的 lint 之前执行更稳。

lint/lint:fix：ESLint 静态检查及自动修复。

format：Prettier 统一代码风格。
test / test:ui / coverage：Vitest 相关脚本；--ui 提供交互界面，--coverage 生成测试覆盖率。
analyze：产物体积分析；rollup-plugin-visualizer 会在 dist/stats.html 展示依赖体积。
prepare：Husky 安装 Git hooks 的标准脚本，必须命名为 prepare 才会在 install 后自动运行。

2.4、依赖分类

dependencies：生产运行时需要的依赖（打包后在浏览器/Node 环境真正使用的）。

这里包括 vue、vue-router、pinia、axios、@vueuse/core 等。
devDependencies：仅开发/构建/测试阶段用到的依赖（如 vite、eslint、vitest、tailwindcss）。

版本前缀建议：库用 ^（允许 MINOR/PATCH 更新），关键编译链（typescript、vite）可用 ~（只放开 PATCH）来降低破坏性升级风险。

2.5、代码质量与提交流程

lint-staged：仅对提交的暂存文件运行 lint/format，速度快、落地有效。需结合 Husky 的 pre-commit 钩子：

.husky/pre-commit 内容示例：npx lint-staged
husky：Git hooks 管理工具。安装后会在项目根生成 .husky/ 目录。

2.6、目标浏览器

browserslist：配置构建目标与 polyfill 范围（PostCSS/Autoprefixer、部分工具会用到）。

常见现代标准如示例；若需要兼容旧端，可改为 "defaults, not IE 11" 等。

2.7、依赖覆盖/强制解析

overrides（npm） / resolutions（yarn）：强制指定某些传递依赖的版本，用于应急修复安全漏洞或规避上游不兼容。

pnpm 推荐使用 "pnpm": { "overrides": { ... } }（见下文"变体与可选字段"）。

注意：盲目覆盖可能造成运行时不兼容，升级后要回滚这些覆盖。

2.8、发布与 Tree Shaking

publishConfig：发布到 npm 的附加配置。私有应用通常不发布，可忽略；库项目常用来指定 access、registry。
sideEffects：供打包器（Vite/Rollup/Webpack）做 Tree Shaking 的提示。false 表示该包没有副作用导入，便于剔除未用代码。

警告：如果项目中有通过 import 引入的全局样式或 polyfill，且会产生副作用，切勿将其标记成 false；否则会被错误删除。此字段更常用于库，应用上使用需慎重。

2.9、法务与追踪

author / license：作者与许可证。企业内应用可标 UNLICENSED；开源库选择合适协议（MIT/Apache-2.0）。
repository / bugs / homepage：用于指向代码仓库、问题反馈与主页，CI 与文档工具会引用。

2.10、运行时版本固定（可选）

volta：若团队使用 Volta 管理 Node/包管器版本，可在此固定，开发机自动匹配。

三、脚本常见扩展（可按需添加）

clean：清理构建产物：rimraf dist（安装 rimraf）。
preview:serve：用静态服务器预览：npx serve -s dist -l 5000。
release：配合 semantic-release 自动发版（库项目更常见）。
preinstall：约束包管理器：npx only-allow pnpm（防止误用 npm/yarn）。

四、依赖清单说明（为何选它们）

核心框架：vue（3.x 主线）、vue-router（路由）、pinia（状态）。
常用工具：axios（HTTP）、@vueuse/core（组合式工具函数集合）。
构建：vite + @vitejs/plugin-vue（必备），@vitejs/plugin-vue-jsx（如用 JSX）。
类型/校验：typescript、vue-tsc（TS 类型检查）。
测试：vitest + @vitest/coverage-v8（覆盖率）。
代码质量：eslint、eslint-plugin-vue、@typescript-eslint/*、prettier、eslint-config-prettier。
提交体验：husky + lint-staged。
分析/调优：rollup-plugin-visualizer（体积可视化）、vite-plugin-inspect（调试插件链）。
样式链路：postcss、autoprefixer，可选 tailwindcss。

五、版本前缀策略（避免"隐性升级"翻车）

^1.2.3：允许 MINOR/PATCH 自动升级（1.x）。适合应用的业务依赖（非构建链）。
~1.2.3：仅允许 PATCH 升级。适合关键构建链（vite/typescript）。
固定版本（无前缀）：完全不漂移。用于临时"止血"。

配合锁文件（pnpm-lock.yaml/package-lock.json/yarn.lock）提交到仓库，确保环境一致。

六、变体与可选字段

6.1、使用 pnpm 的覆盖写法

powershell 复制代码

{
  "pnpm": {
    "overrides": {
      "minimatch": "^9.0.4"
    }
  }
}

6.2、仅 JavaScript 项目（去掉 TS 相关）

删除 typescript、vue-tsc，移除 type-check 脚本。

保留 ESLint（eslint-plugin-vue）与 Prettier 即可。

6.3、 Monorepo（工作空间）

powershell 复制代码

{
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "packageManager": "pnpm@9.6.0"
}

pnpm 推荐用 pnpm-workspace.yaml 管理工作空间范围；yarn/npm 也支持 workspaces。

6.4、发布型库与应用的区别

库需增加：main（CJS 入口）、module（ESM 入口）、types（类型声明）、exports（现代条件导出）、files（发布白名单）。
应用通常不需要这些字段（不会发布到 npm）。

6.5、浏览器兼容更精细

若目标是现代浏览器，可用：["defaults and supports es6-module", "maintained node versions"]。
也可在 vite.config.ts 中通过 build.target 精准控制。

七、落地建议（CI/CD & 团队）

锁定 Node/包管理器版本：engines + packageManager +（可选）volta。
提交锁文件：确保依赖解析一致。
Husky + Lint-Staged：把质量门槛前置到提交阶段。
独立的配置文件（推荐）：将 ESLint/Prettier/Vitest/Tailwind 配置放入各自文件，package.json 保持干净可读。
依赖审计：在 CI 中加入 pnpm audit/npm audit 并结合 overrides 快速修复。

八、常见报错与排查

Unknown script "prepare"：未安装 husky 或未执行 pnpm install。
Cannot find package 'vue'：依赖未安装或 node_modules 被缓存策略清理，执行重新安装。
The engine "node" is incompatible：Node 版本不满足 engines 条件，升级/切换 Node。
构建产物缺样式：检查是否误把有副作用的样式文件在 sideEffects=false 情况下被 treeshake 了。

"人的一生会经历很多痛苦，但回头想想，都是传奇"。

Vue 项目 package.json 终极详解（主流实践 / 逐项说明）

文章目录

一、package.json 完整示例

二、字段逐项详解（用途、取值、坑位）

2.1、元信息

2.2、运行环境与包管理

2.3、脚本（scripts）

2.4、依赖分类

2.5、代码质量与提交流程

2.6、目标浏览器

2.7、依赖覆盖/强制解析

2.8、发布与 Tree Shaking

2.9、法务与追踪

2.10、运行时版本固定（可选）

三、脚本常见扩展（可按需添加）

四、依赖清单说明（为何选它们）

五、版本前缀策略（避免"隐性升级"翻车）

六、变体与可选字段

6.1、 使用 pnpm 的覆盖写法

6.2、 仅 JavaScript 项目（去掉 TS 相关）

6.3、 Monorepo（工作空间）

6.4、 发布型库 与 应用 的区别

6.5、 浏览器兼容更精细

七、落地建议（CI/CD & 团队）

八、常见报错与排查

6.1、使用 pnpm 的覆盖写法

6.2、仅 JavaScript 项目（去掉 TS 相关）

6.4、发布型库与应用的区别

6.5、浏览器兼容更精细