深入理解 package.json的配置文件

前言

以下知识点，结合实战项目进行讲解

1. 基本知识

一个 JSON 格式的配置文件，位于 Node.js 项目的根目录下，包含项目的基本信息、依赖关系、脚本、版本等内容

一般分为几个部分：项目元数据、脚本、依赖关系、配置等

以下是常见的字段：

常见的模版有如下：

{
  "name": "yudao-ui-admin-vue3", // 项目的名称，通常与项目的仓库名称一致
  "version": "2.0.1-snapshot", // 项目的版本号，遵循语义化版本规范，`-snapshot` 表示开发中的版本
  "description": "基于vue3、vite4、element-plus、typesScript", // 项目的简短描述，概述了项目的技术栈
  "author": "xingyu", // 项目的作者信息
  "private": false, // 是否为私有项目，设为 `true` 时，该项目不能发布到 npm
  "scripts": {
    "i": "pnpm install", // 快捷安装依赖包的命令
    "dev": "vite --mode local-dev", // 启动开发服务器，指定为 `local-dev` 模式
    "build:prod": "node --max_old_space_size=8192 ./node_modules/vite/bin/vite.js build --mode prod", // 构建生产环境的打包命令
    "lint:eslint": "eslint --fix --ext .js,.ts,.vue ./src", // 使用 ESLint 自动修复代码格式
    "clean": "npx rimraf node_modules", // 删除 `node_modules` 文件夹，用于清理依赖包
  },
  "dependencies": {
    "vue": "3.4.20", // 项目的核心依赖项 `vue`，指定版本号
    "axios": "^1.6.7", // HTTP 客户端库，使用 `^` 指定兼容的次要版本和修订版本
    "element-plus": "2.5.3" // Vue 3 的 UI 框架，锁定为特定版本
  },
  "devDependencies": {
    "eslint": "^8.57.0", // 开发环境依赖项，用于代码质量检查
    "typescript": "5.3.3", // TypeScript 语言的编译器版本
    "vite": "5.1.4" // 构建工具 Vite 的版本
  },
  "license": "MIT", // 项目的许可证类型，表示开源且允许免费使用
  "repository": {
    "type": "git",
    "url": "git+https://gitee.com/yudaocode/yudao-ui-admin-vue3" // 项目代码库的 URL
  },
  "bugs": {
    "url": "https://gitee.com/yudaocode/yudao-ui-admin-vue3/issues" // 用于报告项目问题的 URL
  },
  "homepage": "https://gitee.com/yudaocode/yudao-ui-admin-vue3", // 项目的主页 URL
  "packageManager": "pnpm@9.0.6", // 指定项目使用的包管理器及其版本
  "engines": {
    "node": ">= 16.0.0", // 指定项目支持的 Node.js 版本
    "pnpm": ">=8.6.0" // 指定项目支持的 pnpm 版本
  }
}

还有如下：

起到的作用如下：

• 版本控制：通过 dependencies 和 devDependencies 指定依赖包的版本，确保项目在不同环境下依然可以正常运行

• 脚本管理：使用 scripts 字段定义常用的命令行脚本，使得开发者可以方便地执行构建、测试、启动等操作

• 私有和公共项目：通过设置 private 字段，可以控制项目是否可以发布到 npm。设为 true 时，项目将不会被意外发布

• 项目元数据：name、version、description 等字段帮助开发者和用户了解项目的基本信息

常常配合npm如下命令：

• npm install：安装 package.json 中定义的所有依赖包

• npm start：执行 scripts 中定义的 start 脚本，通常用于启动开发服务器

• npm run <script>： 执行 scripts 中定义的自定义脚本，如 npm run build 或 npm run lint

• npm test：执行 scripts 中定义的 test 脚本，通常用于运行项目的单元测试

• npm install <package>：安装特定的包，并自动将其添加到 dependencies 中

• npm install <package> --save-dev：安装特定的包，并将其添加到 devDependencies 中

2. 实战讲解

结合实战中的package.json进行详细分析

{
  "name": "manong",  // 项目的名称，通常用来标识此项目的名称
  "version": "2.0.1-snapshot",  // 项目的版本号，用于版本控制
  "description": "基于vue3、vite4、element-plus、typesScript",  // 对项目的简短描述
  "author": "manong",  // 项目的作者信息
  "private": false,  // 设置为 true 时，防止此包被发布到 npm 仓库
  "scripts": {
    "i": "pnpm install",  // 快捷命令，用于安装依赖包，等同于 `pnpm install`
    "dev": "vite --mode local-dev",  // 在 local-dev 模式下启动开发服务器
    "dev-server": "vite --mode dev",  // 在 dev 模式下启动开发服务器
    "ts:check": "vue-tsc --noEmit",  // 检查 TypeScript 类型错误，但不输出文件
    "build:local-dev": "node --max_old_space_size=8192 ./node_modules/vite/bin/vite.js build --mode local-dev",  // 在 local-dev 模式下构建项目，增加了 Node.js 内存限制
    "build:dev": "node --max_old_space_size=8192 ./node_modules/vite/bin/vite.js build --mode local-dev",  // 在 dev 模式下构建项目
    "build:test": "node --max_old_space_size=8192 ./node_modules/vite/bin/vite.js build --mode test",  // 在 test 模式下构建项目
    "build:stage": "node --max_old_space_size=8192 ./node_modules/vite/bin/vite.js build --mode stage",  // 在 stage 模式下构建项目
    "build:prod": "node --max_old_space_size=8192 ./node_modules/vite/bin/vite.js build --mode prod",  // 在 prod 模式下构建项目
    "serve:dev": "vite preview --mode dev",  // 在 dev 模式下预览已构建的项目
    "serve:prod": "vite preview --mode prod",  // 在 prod 模式下预览已构建的项目
    "preview": "pnpm build:local-dev && vite preview",  // 构建 local-dev 模式并预览
    "clean": "npx rimraf node_modules",  // 删除 node_modules 文件夹
    "clean:cache": "npx rimraf node_modules/.cache",  // 删除 node_modules 中的缓存文件夹
    "lint:eslint": "eslint --fix --ext .js,.ts,.vue ./src",  // 运行 ESLint 进行代码检查，并尝试自动修复问题
    "lint:format": "prettier --write --loglevel warn \"src/**/*.{js,ts,json,tsx,css,less,scss,vue,html,md}\"",  // 使用 Prettier 格式化代码
    "lint:style": "stylelint --fix \"./src/**/*.{vue,less,postcss,css,scss}\" --cache --cache-location node_modules/.cache/stylelint/",  // 使用 Stylelint 检查和修复样式文件
    "lint:lint-staged": "lint-staged -c "  // 仅对 Git 暂存区中的文件运行 lint-staged
  },
  "dependencies": {  // 生产环境依赖的库和模块
    "@element-plus/icons-vue": "^2.1.0",  // Element Plus 图标库的 Vue 3 版本
    "@form-create/designer": "^3.1.3",  // form-create 的表单设计器
    "@form-create/element-ui": "^3.1.24",  // form-create 和 Element UI 的集成
    "@iconify/iconify": "^3.1.1",  // 图标组件库
    "@videojs-player/vue": "^1.0.0",  // Video.js 播放器的 Vue 组件封装
    "@vueuse/core": "^10.9.0",  // VueUse 是一组实用程序的集合，用于增强 Vue 3 的能力
    "@wangeditor/editor": "^5.1.23",  // WangEditor 是一个富文本编辑器
    "@wangeditor/editor-for-vue": "^5.1.10",  // WangEditor 为 Vue 的集成版本
    "@zxcvbn-ts/core": "^3.0.4",  // Zxcvbn 是一个密码强度检测库
    "animate.css": "^4.1.1",  // CSS 动画库
    "axios": "^1.6.7",  // HTTP 请求库
    "benz-amr-recorder": "^1.1.5",  // 用于录制和播放 AMR 格式的 JavaScript 库
    "bpmn-js-token-simulation": "^0.10.0",  // 用于 BPMN 2.0 的令牌模拟器
    "camunda-bpmn-moddle": "^7.0.1",  // 用于 BPMN 2.0 的 Camunda 扩展模型
    "cropperjs": "^1.6.1",  // 图像裁剪库
    "crypto-js": "^4.2.0",  // 加密库
    "dayjs": "^1.11.10",  // 轻量级的日期处理库
    "diagram-js": "^12.8.0",  // 用于 BPMN、DMN 和 CMMN 的基础图表库
    "driver.js": "^1.3.1",  // 用户引导库
    "echarts": "^5.5.0",  // 图表库
    "echarts-wordcloud": "^2.1.0",  // ECharts 的词云图扩展
    "element-plus": "2.5.3",  // Element Plus 是一款基于 Vue 3 的 UI 组件库
    "fast-xml-parser": "^4.3.2",  // 快速解析 XML 文件的库
    "highlight.js": "^11.9.0",  // 代码高亮库
    "jsencrypt": "^3.3.2",  // JavaScript 实现的 RSA 加密库
    "lodash-es": "^4.17.21",  // JavaScript 实用工具库的 ES 模块版本
    "min-dash": "^4.1.1",  // 轻量级的工具库
    "mitt": "^3.0.1",  // 用于事件处理的库
    "nprogress": "^0.2.0",  // 顶部加载进度条
    "pinia": "^2.1.7",  // Vue 的状态管理库
    "pinia-plugin-persistedstate": "^3.2.0",  // Pinia 的持久化插件
    "qrcode": "^1.5.3",  // 生成二维码的库
    "qs": "^6.11.2",  // 查询字符串解析和序列化库
    "steady-xml": "^0.1.0",  // 处理 XML 数据的库
    "url": "^0.11.3",  // URL 处理库
    "video.js": "^7.21.5",  // 视频播放器库
    "vue": "3.4.20",  // Vue.js 框架的版本
    "vue-dompurify-html": "^4.1.4",  // 防止 XSS 攻击的库
    "vue-i18n": "9.9.1",  // Vue.js 的国际化插件
    "vue-router": "^4.3.0",  // Vue.js 的路由管理器
    "vue-types": "^5.1.1",  // Prop 验证工具
    "vuedraggable": "^4.1.0",  // 拖拽排序组件
    "web-storage-cache": "^1.1.1",  // Web 存储的缓存库
    "xml-js": "^1.6.11"  // 将 XML 转换为 JavaScript 对象的库
  },
  "devDependencies": {  // 开发环境依赖的库和模块
    "@commitlint/cli": "^19.0.1",  // 用于 lint 提交信息的命令行工具
    "@commitlint/config-conventional": "^19.0.0",  // commitlint 的常规配置
    "@iconify/json": "^2.2.187",  // 图标数据的 JSON 文件
    "@intlify/unplugin-vue-i18n": "^2.0.0",  // Vue I18n 的插件
    "@purge-icons/generated": "^0.9.0",  // PurgeIcons 的生成文件
    "@types/lodash-es": "^4.17.12",  // lodash-es 的 TypeScript 类型定义
    "@types/node": "^20.11.21",  // Node.js 的 TypeScript 类型定义
    "@types/qs": "^6.9.7",  // qs 的 TypeScript 类型定义
    "@vitejs/plugin-vue": "^4.3.5",  // Vue.js 的 Vite 插件
    "@vitejs/plugin-vue-jsx": "^4.3.5",  // Vue.js 的 JSX 插件
    "@vue/compiler-sfc": "^3.4.20",  // Vue.js 的单文件组件编译器
    "@vue/eslint-config-prettier": "^9.0.2",  // 与 ESLint 配合使用的 Prettier 配置
    "@vue/eslint-config-typescript": "^11.0.1",  // TypeScript 的 ESLint 配置
    "autoprefixer": "^10.4.16",  // 自动为 CSS 添加浏览器前缀的工具
    "conventional-changelog-cli": "^5.1.1",  // 生成规范化变更日志的命令行工具
    "eslint": "^8.51.0",  // JavaScript 和 TypeScript 代码的静态分析工具
    "eslint-plugin-import": "^2.28.1",  // 支持 ES6+ 导入语法的 ESLint 插件
    "eslint-plugin-prettier": "^4.2.1",  // 将 Prettier 集成到 ESLint 的插件
    "eslint-plugin-vue": "^9.20.0",  // 支持 Vue.js 语法的 ESLint 插件
    "husky": "^8.0.3",  // Git 钩子的管理工具
    "lint-staged": "^14.0.1",  // 在提交代码之前只对暂存区中的文件运行 linters
    "postcss": "^8.4.30",  // CSS 转换工具
    "postcss-html": "^1.5.0",  // PostCSS 插件，用于解析 HTML 文件
    "postcss-less": "^6.0.1",  // PostCSS 插件，用于解析 Less 文件
    "postcss-load-config": "^4.0.1",  // 加载 PostCSS 配置的工具
    "postcss-preset-env": "^9.1.3",  // 将现代 CSS 转换为兼容性较好的 CSS
    "prettier": "^3.0.3",  // 代码格式化工具
    "sass": "^1.66.1",  // CSS 的扩展语言
    "stylelint": "^15.10.1",  // CSS 和 SCSS 代码的静态分析工具
    "stylelint-config-html": "^1.3.0",  // HTML 文件的 Stylelint 配置
    "stylelint-config-prettier": "^9.0.4",  // 与 Prettier 配合使用的 Stylelint 配置
    "stylelint-config-recommended-vue": "^1.7.0",  // Vue.js 推荐的 Stylelint 配置
    "stylelint-config-standard": "^34.0.0",  // 标准的 Stylelint 配置
    "stylelint-config-standard-scss": "^10.0.0",  // 标准的 SCSS 文件 Stylelint 配置
    "stylelint-order": "^6.0.4",  // 用于排序 CSS 属性的 Stylelint 插件
    "typescript": "^5.2.2",  // TypeScript 编译器
    "unplugin-auto-import": "^0.17.7",  // 自动导入依赖的插件
    "unplugin-icons": "^0.19.15",  // 用于图标的自动导入和使用
    "unplugin-vue-components": "^0.24.1",  // Vue 组件的自动导入插件
    "vite": "^4.3.9",  // Vite 是一个前端构建工具
    "vite-plugin-compression": "^0.6.2",  // 用于压缩文件的 Vite 插件
    "vite-plugin-html": "^3.2.0",  // 用于增强 HTML 文件的 Vite 插件
    "vite-plugin-mock": "^3.1.0",  // 用于模拟 API 请求的 Vite 插件
    "vite-plugin-pwa": "^0.17.0",  // 使应用支持 PWA 的 Vite 插件
    "vite-plugin-svg-icons": "^2.0.1",  // 用于处理 SVG 图标的 Vite 插件
    "vite-plugin-vue-setup-extend": "^0.4.0",  // 使 Vue 的 setup 语法支持扩展的 Vite 插件
    "vite-plugin-vue-setup-extend-plus": "^1.0.8",  // 另一个用于扩展 Vue setup 的插件
    "vite-plugin-windicss": "^2.7.4",  // 用于集成 WindiCSS 的 Vite 插件
    "vue-tsc": "^1.9.6"  // Vue 的 TypeScript 编译器
  },
  "lint-staged": {  // 配置 lint-staged 的规则
    "*.{js,jsx,ts,tsx,vue}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,vue,less,postcss}": [
      "stylelint --fix"
    ],
    "*.{md,json}": [
      "prettier --write"
    ]
  },
  "engines": {  // 指定项目的 Node.js 版本要求
    "node": ">=16.0.0"
  },
  "packageManager": "pnpm@8.7.5"  // 项目使用的包管理工具及其版本
}