Vue 项目 package.json 完整示例详解(主流实践 / 逐项说明)

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

一、package.json 完整示例

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

{
"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 的覆盖写法

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

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

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

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

6.3、 Monorepo（工作空间）

{
  "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 完整示例详解(主流实践 / 逐项说明)的文章就介绍到这了,更多相关vue package.json内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

最新评论