一、示例 / 详细注释说明

{// 项目基础信息"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