面向 Vue3 + Vite 技術(shù)棧，附完整示例與每個(gè)字段的用途、取值建議、易踩坑位。示例采用 TypeScript + Pinia + Vue Router + Vitest + ESLint + Prettier + Husky + Lint-Staged，并固定包管理器為 pnpm（可切換為 npm/yarn）。

一、package.json 完整示例

一個(gè)主流的 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）二者并存僅為演示，實(shí)際項(xiàng)目按所用包管理器擇一；pnpm 推薦使用 pnpm.overrides（見下文“變體”）。

二、字段逐項(xiàng)詳解（用途、取值、坑位）

2.1、元信息

• name：包名/應(yīng)用名（npm 規(guī)則：小寫、連字符）。私有應(yīng)用也建議規(guī)范命名，利于 CI 與制品追蹤。
• version：語義化版本（MAJOR.MINOR.PATCH）。應(yīng)用可以不頻繁改，但發(fā)版/制品追蹤建議維護(hù)。
• private：為 true 時(shí)禁止被 npm publish 誤發(fā)布，強(qiáng)烈建議應(yīng)用項(xiàng)目開啟。
• description / keywords：用于人類/搜索，CI 報(bào)表、文檔站點(diǎn)也會用到。

2.2、運(yùn)行環(huán)境與包管理

• packageManager：鎖定包管理器與版本（如 pnpm@9.6.0），避免團(tuán)隊(duì)環(huán)境差異。
• type：“module” 表示 Node 端默認(rèn)使用 ESM；配合 Vite/現(xiàn)代前端更一致。若使用 CJS，改為省略或顯式 “commonjs”。
• engines：聲明 Node/包管理器版本范圍，CI/CD 可據(jù)此拒絕不兼容環(huán)境。
• 例：“node”: “>=18.18 <23” 兼顧 LTS 與 Vite 5 要求。

2.3、腳本（scripts）

• dev：本地開發(fā)啟動 Vite 開發(fā)服務(wù)器。
• build：執(zhí)行生產(chǎn)構(gòu)建，輸出到 dist/。
• preview：本地預(yù)覽生產(chǎn)構(gòu)建產(chǎn)物；–strictPort 避免自動換端口導(dǎo)致腳本監(jiān)控混亂。
• type-check：僅做 TS 類型檢查，不產(chǎn)出文件；在 CI 的 lint 之前執(zhí)行更穩(wěn)。

lint/lint:fix：ESLint 靜態(tài)檢查及自動修復(fù)。

• format：Prettier 統(tǒng)一代碼風(fēng)格。
• test / test:ui / coverage：Vitest 相關(guān)腳本；–ui 提供交互界面，–coverage 生成測試覆蓋率。
• analyze：產(chǎn)物體積分析；rollup-plugin-visualizer 會在 dist/stats.html 展示依賴體積。
• prepare：Husky 安裝 Git hooks 的標(biāo)準(zhǔn)腳本，必須命名為 prepare 才會在 install 后自動運(yùn)行。

2.4、依賴分類

• dependencies：生產(chǎn)運(yùn)行時(shí)需要的依賴（打包后在瀏覽器/Node 環(huán)境真正使用的）。
• 這里包括 vue、vue-router、pinia、axios、@vueuse/core 等。
• devDependencies：僅開發(fā)/構(gòu)建/測試階段用到的依賴（如 vite、eslint、vitest、tailwindcss）。
• 版本前綴建議：庫用 ^（允許 MINOR/PATCH 更新），關(guān)鍵編譯鏈（typescript、vite）可用 ~（只放開 PATCH）來降低破壞性升級風(fēng)險(xiǎn)。

2.5、代碼質(zhì)量與提交流程

• lint-staged：僅對提交的暫存文件運(yùn)行 lint/format，速度快、落地有效。需結(jié)合 Husky 的 pre-commit 鉤子：
• .husky/pre-commit 內(nèi)容示例：npx lint-staged
• husky：Git hooks 管理工具。安裝后會在項(xiàng)目根生成 .husky/ 目錄。

2.6、目標(biāo)瀏覽器

• browserslist：配置構(gòu)建目標(biāo)與 polyfill 范圍（PostCSS/Autoprefixer、部分工具會用到）。
• 常見現(xiàn)代標(biāo)準(zhǔn)如示例；若需要兼容舊端，可改為 “defaults, not IE 11” 等。

2.7、依賴覆蓋/強(qiáng)制解析

• overrides（npm） / resolutions（yarn）：強(qiáng)制指定某些傳遞依賴的版本，用于應(yīng)急修復(fù)安全漏洞或規(guī)避上游不兼容。
• pnpm 推薦使用 “pnpm”: { “overrides”: { … } }（見下文“變體與可選字段”）。
• 注意：盲目覆蓋可能造成運(yùn)行時(shí)不兼容，升級后要回滾這些覆蓋。

2.8、發(fā)布與 Tree Shaking

• publishConfig：發(fā)布到 npm 的附加配置。私有應(yīng)用通常不發(fā)布，可忽略；庫項(xiàng)目常用來指定 access、registry。
• sideEffects：供打包器（Vite/Rollup/Webpack）做 Tree Shaking 的提示。false 表示該包沒有副作用導(dǎo)入，便于剔除未用代碼。
• 警告：如果項(xiàng)目中有通過 import 引入的全局樣式或 polyfill，且會產(chǎn)生副作用，切勿將其標(biāo)記成 false；否則會被錯誤刪除。此字段更常用于庫，應(yīng)用上使用需慎重。

2.9、法務(wù)與追蹤

• author / license：作者與許可證。企業(yè)內(nèi)應(yīng)用可標(biāo) UNLICENSED；開源庫選擇合適協(xié)議（MIT/Apache-2.0）。
• repository / bugs / homepage：用于指向代碼倉庫、問題反饋與主頁，CI 與文檔工具會引用。

2.10、運(yùn)行時(shí)版本固定（可選）

• volta：若團(tuán)隊(duì)使用 Volta 管理 Node/包管器版本，可在此固定，開發(fā)機(jī)自動匹配。

三、腳本常見擴(kuò)展（可按需添加）

• clean：清理構(gòu)建產(chǎn)物：rimraf dist（安裝 rimraf）。
• preview:serve：用靜態(tài)服務(wù)器預(yù)覽：npx serve -s dist -l 5000。
• release：配合 semantic-release 自動發(fā)版（庫項(xiàng)目更常見）。
• preinstall：約束包管理器：npx only-allow pnpm（防止誤用 npm/yarn）。

四、依賴清單說明（為何選它們）

• 核心框架：vue（3.x 主線）、vue-router（路由）、pinia（狀態(tài)）。
• 常用工具：axios（HTTP）、@vueuse/core（組合式工具函數(shù)集合）。
• 構(gòu)建：vite + @vitejs/plugin-vue（必備），@vitejs/plugin-vue-jsx（如用 JSX）。
• 類型/校驗(yàn)：typescript、vue-tsc（TS 類型檢查）。
• 測試：vitest + @vitest/coverage-v8（覆蓋率）。
• 代碼質(zhì)量：eslint、eslint-plugin-vue、@typescript-eslint/*、prettier、eslint-config-prettier。
• 提交體驗(yàn)：husky + lint-staged。
• 分析/調(diào)優(yōu)：rollup-plugin-visualizer（體積可視化）、vite-plugin-inspect（調(diào)試插件鏈）。
• 樣式鏈路：postcss、autoprefixer，可選 tailwindcss。

五、版本前綴策略（避免“隱性升級”翻車）

• ^1.2.3：允許 MINOR/PATCH 自動升級（1.x）。適合應(yīng)用的業(yè)務(wù)依賴（非構(gòu)建鏈）。
• ~1.2.3：僅允許 PATCH 升級。適合關(guān)鍵構(gòu)建鏈（vite/typescript）。
• 固定版本（無前綴）：完全不漂移。用于臨時(shí)“止血”。

配合鎖文件（pnpm-lock.yaml/package-lock.json/yarn.lock）提交到倉庫，確保環(huán)境一致。

六、變體與可選字段

6.1、 使用 pnpm 的覆蓋寫法

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

6.2、 僅 JavaScript 項(xiàng)目（去掉 TS 相關(guān)）

刪除 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、 發(fā)布型庫 與 應(yīng)用 的區(qū)別

• 庫需增加：main（CJS 入口）、module（ESM 入口）、types（類型聲明）、exports（現(xiàn)代條件導(dǎo)出）、files（發(fā)布白名單）。
• 應(yīng)用通常不需要這些字段（不會發(fā)布到 npm）。

6.5、 瀏覽器兼容更精細(xì)

• 若目標(biāo)是現(xiàn)代瀏覽器，可用：[“defaults and supports es6-module”, “maintained node versions”]。
• 也可在 vite.config.ts 中通過 build.target 精準(zhǔn)控制。

七、落地建議（CI/CD & 團(tuán)隊(duì)）

• 鎖定 Node/包管理器版本：engines + packageManager +（可選）volta。
• 提交鎖文件：確保依賴解析一致。
• Husky + Lint-Staged：把質(zhì)量門檻前置到提交階段。
• 獨(dú)立的配置文件（推薦）：將 ESLint/Prettier/Vitest/Tailwind 配置放入各自文件，package.json 保持干凈可讀。
• 依賴審計(jì)：在 CI 中加入 pnpm audit/npm audit 并結(jié)合 overrides 快速修復(fù)。

八、常見報(bào)錯與排查

• Unknown script “prepare”：未安裝 husky 或未執(zhí)行 pnpm install。
• Cannot find package ‘vue’：依賴未安裝或 node_modules 被緩存策略清理，執(zhí)行重新安裝。
• The engine “node” is incompatible：Node 版本不滿足 engines 條件，升級/切換 Node。
• 構(gòu)建產(chǎn)物缺樣式：檢查是否誤把有副作用的樣式文件在 sideEffects=false 情況下被 treeshake 了。

到此這篇關(guān)于Vue 項(xiàng)目 package.json 完整示例詳解(主流實(shí)踐 / 逐項(xiàng)說明)的文章就介紹到這了,更多相關(guān)vue package.json內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論