一、示例 / 详细注释说明
{
// 项目基础信息
"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
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