理解 package-lock.json 何时推送与忽略

news2025/1/25 4:01:46

package.json 和 package-lock.json 是 Node.js 和前端开发中的核心配置文件，管理着项目的依赖关系、脚本和其他重要配置。下面简单介绍下这两个文件以及它们的使用规则。

1. package.json

package.json 是 Node.js 和 JavaScript 项目的配置文件，它包含了项目的元数据（如名称、版本、描述等）以及项目的依赖管理。

1.1 项目元数据

1、name：项目的名称。必须是小写字母和中划线（-）的组合，通常用于 npm 包发布。

2、version：项目的版本，遵循 semver（语义化版本）规范。

3、main：指定该项目的入口文件，通常是 index.js。

4、scripts：定义 npm 脚本命令，比如：npm start、npm run build 等，这些命令可以用于自动化执行构建、测试等操作。

5、description：项目的简短描述，通常是对项目功能的概述。

🌰

{
  "name": "my-vue-app",
  "version": "1.0.0",
  "description": "A Vue.js application",
  "main": "index.js"
}

1.2 依赖管理

package.json 文件指定了项目的依赖，分为两种类型：

1、dependencies：项目在运行时需要的依赖。一般来说，这些是项目正常运行时必需的库和工具。

2、devDependencies：开发过程中需要的依赖。比如，构建工具、测试工具、开发服务器等。

🌰

{
  "dependencies": {
    "vue": "^3.2.0",
    "axios": "^0.21.0"
  },
  "devDependencies": {
    "webpack": "^5.0.0",
    "babel-loader": "^8.2.2"
  }
}

1.3 脚本管理

package.json 文件中的 scripts 字段允许我们自定义命令，可以让开发者通过 npm 或 yarn 来执行一系列的构建任务。比如：配置 build、serve、test 等命令。

常见的脚本包括：

- start：启动开发服务器，通常会调用 vue-cli-service serve 或其他工具来启动一个本地开发环境。

- build：用于构建生产环境的代码，通常会调用 vue-cli-service build 进行打包。

- test：执行单元测试。

🌰

{
  "scripts": {
    "start": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "test": "jest"
  }
}

1.4 版本控制

package.json 中的 version 字段遵循 semver（语义化版本）规范规则，帮助团队和开发者清楚地了解每个版本的变化。

- 主版本号（major）：当修改了不兼容的 API，增加了破坏性的改动时，升级主版本号。

- 次版本号（minor）：当向下兼容的功能中增加了新功能时，升级次版本号。

- 修订版本号（patch）：当修复了向下兼容的问题时，升级修订版本号。

🌰

{
  "version": "1.2.3"
}

1.5 package.json 的目的

1、简化项目配置

将项目的关键信息、脚本、依赖等内容集中存储，方便开发者和构建工具访问和管理。

2、共享项目依赖

通过 npm install 或 yarn install 安装依赖时，package.json 文件会根据预设的依赖版本范围安装匹配的依赖。

2. package-lock.json

package-lock.json 是自动生成的文件，用于锁定所有项目依赖的版本，以确保每次安装依赖时使用相同版本的包。这个文件不会手动编辑，它会由 npm install 自动创建和更新。

2.1 作用

1、锁定依赖版本

package-lock.json 中记录了 node_modules 中每个依赖包的确切版本。这样即便 package.json 中的版本范围使用的是类似 ^ 或 ~ 这种可变的版本号，package-lock.json 会确保每次 npm install 时，依赖的版本是相同的。

2、提高安装速度

由于 package-lock.json 中包含了每个包的准确版本信息，npm 可以更快地查找依赖并避免不必要的版本解析。

3、确保一致性

保证团队中的每个开发者和 CI/CD 环境中使用相同的依赖版本，避免了 "works on my machine" 的问题。

2.2 文件内容 🌰

{
  "name": "my-project",
  "version": "1.0.0",
  "lockfileVersion": 1,
  "dependencies": {
    "express": {
      "version": "4.17.1",
      "resolved": "https://registry.npmjs.org/express/-/express-4.17.1.tgz",
      "integrity": "sha512-...",
      "dev": false
    },
    "lodash": {
      "version": "4.17.21",
      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
      "integrity": "sha512-..."
    }
  }
}

字段解释：

1、lockfileVersion：指示 package-lock.json 的版本，当前为版本 1。

2、dependencies：每个依赖项的详细信息，包括：

- version：该依赖的确切版本。

- resolved：依赖包的 tarball URL。

- integrity：包内容的校验，用于确保下载的包没有被篡改。

- dev：指示依赖是开发依赖还是生产依赖。