一、示例 / 詳細注釋說明

{// 項目基礎信息"name": "vite-project", // 項目名稱（建議使用 kebab-case 格式）"private": true,        // 標記為私有項目，避免意外發布到 npm"version": "1.0.0",     // 項目版本（遵循語義化版本規范）"type": "module",       // 聲明使用 ES Modules（ESM）規范"description": "Vue 3 + TypeScript starter template", // 項目描述"keywords": [           // npm 搜索關鍵詞"vue3","typescript","vite","starter-template","general","config"],// 腳本命令（通過 `yarn run <script>` 或 `npm run <script>` 執行）"scripts": {"tsc": "vue-tsc -b",                     // 類型檢查（Vue + TypeScript）"dev": "vite --mode dev",                // 啟動開發服務器（指定 dev 環境）"test": "vite --mode test",              // 測試環境啟動"uat": "vite --mode uat",                // UAT（用戶驗收測試）環境啟動"pre": "vite --mode pre",                // 預發布環境啟動"production": "vite --mode production",  // 生產環境啟動"build": "yarn tsc && vite build",       // 構建生產包（先類型檢查再構建）"preview": "vite preview",               // 本地預覽生產構建結果"prepare": "husky",                      // 安裝 husky 鉤子（通常用于 Git 鉤子）"format": "prettier --write \"./**/*.{js,jsx,ts,tsx,css,scss,json,md}\"", // 格式化代碼"build-storybook": "cd ./m-general && yarn build-storybook && cd ../",   // 構建 Storybook"subm": "node sub-scripts.js",           // 自定義腳本（如子模塊操作）"postsubm": "cd ./m-general && (pnpm install || yarn install) && cd ../", // subm 后的操作"storybook": "cd ./m-general && yarn storybook && cd ../" // 啟動 Storybook},// 項目依賴（運行時需要的包）"dependencies": {"@element-plus/icons-vue": "^2.3.2", // Element Plus 圖標庫"@types/qrcode": "^1.5.5",          // QRCode 類型定義（通常應放在 devDependencies）"axios": "^1.11.0",                 // HTTP 客戶端"dayjs": "^1.11.13",                // 輕量級日期處理庫"element-plus": "^2.10.6",          // Vue 3 UI 組件庫"js-cookie": "^3.0.5",              // Cookie 操作工具"js-md5": "^0.8.3",                 // MD5 加密"lodash-es": "^4.17.21",            // 工具庫（ESM 版本）"pinia": "^3.0.2",                  // Vue 狀態管理"pinia-plugin-persistedstate": "^4.5.0", // Pinia 持久化插件"qrcode": "^1.5.4",                 // QR 碼生成（生產依賴正確）"vue": "^3.5.13",                   // Vue 3 核心庫"vue-cropper": "^1.1.4",            // 圖片裁剪組件"vue-global-api": "^0.4.1",         // 全局 API 擴展（如 $filters）"vue-router": "^4.5.1",             // Vue 官方路由"vue-ueditor-wrap": "^3.0.8"        // UEditor 封裝（注意：非官方維護）},// 開發依賴（僅開發環境需要的包）"devDependencies": {"@commitlint/cli": "^19.8.1",               // Git 提交信息校驗"@commitlint/config-conventional": "^19.8.1", // 常規提交規范"@types/js-cookie": "^3.0.6",               // js-cookie 類型定義"@types/js-md5": "^0.8.0",                  // js-md5 類型定義"@types/lodash-es": "^4.17.12",             // lodash-es 類型定義"@types/node": "^24.2.1",                   // Node.js 類型定義"@vitejs/plugin-vue": "^5.2.4",             // Vite 的 Vue 插件"@vitejs/plugin-vue-jsx": "^4.2.0",         // Vite 的 Vue JSX 支持"@vitest/browser": "^3.2.2",                // Vitest 瀏覽器測試"@vitest/coverage-v8": "^3.2.2",            // Vitest 覆蓋率報告"@vue/tsconfig": "^0.7.0",                  // Vue 官方 TS 配置模板"commitlint": "^19.8.1",                    // Commitlint 核心（已包含在 cli 中，可移除）"husky": "^9.1.4",                          // Git 鉤子工具"lint-staged": "^16.1.5",                   // 預提交代碼檢查"playwright": "^1.54.2",                    // E2E 測試框架"pnpm": "^10.14.0",                         // pnpm 包管理器（通常不需要聲明）"prettier": "^3.5.3",                       // 代碼格式化工具"sass-embedded": "^1.90.0",                 // Dart Sass 嵌入式版本（性能更好）"shelljs": "^0.10.0",                       // Node.js Shell 工具（用于腳本）"stylelint-config-recommended-scss": "^16.0.0", // SCSS 推薦規則"stylelint-config-standard": "^39.0.0",     // CSS 標準規則"stylelint-scss": "^6.12.0",                // SCSS 語法支持"terser": "^5.40.0",                        // JS 壓縮工具（Vite 默認已集成）"typescript": "~5.9.2",                     // TypeScript（建議固定次要版本）"vite": "^7.1.2",                           // Vite 構建工具"vite-plugin-checker": "^0.10.2",           // 開發時類型/語法檢查"vite-plugin-vue-setup-extend": "^0.4.0",   // 擴展 Vue 的 setup 語法糖"vitest": "^3.2.2",                         // Vite 測試框架"vue-tsc": "^3.0.5"                         // Vue 的 TypeScript 編譯器},// Husky 配置（Git 鉤子）"husky": {"hooks": {"pre-commit": "lint-staged",      // 提交前執行 lint-staged"commit-msg": "commitlint -E HUSKY_GIT_PARAMS" // 提交信息校驗}},// Lint-staged 配置（僅對暫存區文件執行檢查）"lint-staged": {"*.{js,jsx,ts,tsx,css,scss,json,md,yaml,yml}": ["prettier --write" // 格式化],"*.{css,scss,less}": ["stylelint --fix" // 修復 CSS 問題]},// PNPM 特定配置（避免安裝某些依賴）"pnpm": {"ignoredBuiltDependencies": ["@parcel/watcher", // 忽略原生模塊（可能因平臺不兼容導致問題）"esbuild",         // Vite 內部使用，無需重復安裝"vue-demi"         // 兼容 Vue 2/3 的庫（通常不需要顯式安裝）]},// 瀏覽器兼容性配置（Babel/Autoprefixer 使用）"browserslist": ["> 0.5%",        // 全球使用率 > 0.5% 的瀏覽器"last 2 versions", // 每個瀏覽器的最近兩個版本"not dead",      // 排除已停止維護的瀏覽器"not ie <= 11"   // 排除 IE 11 及以下版本]
}

二、過程記錄

2.1、實際JSON文件中不允許有注釋

2.2、browserslist

Browserslist

2.2.1、現代項目（支持最新瀏覽器，放棄舊版）

// package.json
{"browserslist": ["last 2 Chrome versions","last 2 Firefox versions","last 2 Safari versions","last 2 Edge versions","not dead"  // 排除已停止維護的瀏覽器（如 IE 10及以下）]
}

2.2.2、主流兼容項目（覆蓋大部分用戶）

{"browserslist": ["> 0.5%",          // 全球使用率 > 0.5% 的瀏覽器"last 2 versions",  // 每個瀏覽器的最近兩個版本"not dead",        // 排除已停止維護的瀏覽器"not ie <= 11"     // 顯式排除 IE 11（可選）]
}

2.2.3、兼容舊版瀏覽器（包括 IE 11）

{"browserslist": ["> 0.5%","last 2 versions","not dead","IE 11"  // 顯式包含 IE 11]
}

2.2.4、更嚴格的版本（如需支持企業內網舊瀏覽器）

{"browserslist": ["defaults",          // 等同于 "> 0.5%, last 2 versions, not dead""IE 10-11",         // 包含 IE 10 和 11"Firefox ESR",      // 包含 Firefox 擴展支持版本（企業常用）"not < 0.25%"       // 排除使用率極低的瀏覽器]
}

2.2.5、優先移動端瀏覽器 /?H5 / 小程序

{"browserslist": ["iOS >= 10",       // 覆蓋大部分 iPhone"Android >= 5",    // 覆蓋 Android 5+（Chrome 60+）"not dead"]
}

2.2.6、僅需兼容 Node.js 運行時

{"browserslist": ["node 16",  // 根據項目實際 Node 版本調整"node 18"]
}

2.2.7、環境區分（開發/生產）

{"browserslist": {"production": ["> 0.2%","not dead","not op_mini all"],"development": ["last 1 Chrome version",  // 開發時僅支持最新 Chrome"last 1 Firefox version"]}
}

2.2.8、排除特定瀏覽器

{"browserslist": ["> 1%","not IE 11",       // 排除 IE 11"not Samsung 4"   // 排除三星舊版瀏覽器（如 Galaxy S4 內置瀏覽器）]
}

2.2.9、查看生效的瀏覽器列表

npx browserslist