前端 package.json 的每一项作用

前端 package.json 的每一项作用

在 Node.js 项目中，package.json 是一个非常重要的配置文件，它包含了项目的元数据和配置信息。下面是所涉及到的字段含义和它的使用场景，避免一些配置性的错误，提高项目的维护性。

name:

• 作用： 指定包的名称，项目是需要发版为 npm 包的，name 则必填。
• 注意事项： 包名必须是唯一的，且符合 npm 的包命名规范。
• 私源 npm 包命名格式: name:@[scope]/[name]

{
    "name": "custom-npm-xxx"
    //...
}

version:

• 作用： 指定包的当前版本号。
• 版本号格式：X.Y.Z[-string],参考以下规范 ↓
  • X：主版本号
  • Y：次版本号
  • Z：修正版本号
  • string: 先行版本号或版本编译信息

{
    "version": "2.3.2"
    //...
}

扩展阅读

2.3.2-alpha的含义为：

主版本号2，有2次不可向下兼容的更新迭代。
次版本号3，有3次小的功能迭代。2.*.* <=2.3.2的依赖声明，都可以安装此新包。
修正版本号2，有2次bug修改或其他非重大功能的修改。2.*.* <=2.3.2的依赖声明，都可以安装此新包。
先行版本号alpha，表示处理试验阶段。

package.json 识别依赖版本

{
    "vue": "~2.5.22",
    "vue-class-component": "^6.0.0",
    "vue-router": "3.0.1",
    "express": "latest",
    "mongoose": "*"
}

• 符号^：锁定主版本，可更新次版本号、修正版本号和先行版本号

  • 例如"vue-class-component": “^6.0.0”，安装依赖时，可以安装符合 6.. 的任意版本，只要主版本号是 6 即可。

• 符号~：锁定主版本号和次版本号，可更新修正版本号和先行版本号

  • 例如"vue": “~2.5.22”，安装依赖时，可以安装符合 2.5.*的任意版本。

• 空符号：锁定所有版本号

  • 例如"vue-router": “3.0.1”，只能安装版本为 3.0.1 的依赖包。

• 符号*：定义某个版本号范围

  • 例如 vue-router": “3.0.*”，可以安装 3.0 固定的任意版本，比如 3.0.1、3.0.2。

• latest：安装最新的稳定版本。

• 安装最新发布的版本，不一定是稳定版本。

• Git URL：使用 Git 上发布的包。

dependencies:

• 作用： 指定包运行时的依赖项，生产环境中使用到的依赖，安装在该配置项下。
• 注意事项： 使用对象格式，键为依赖包名称，值为版本号范围或者 URL。

{
    "name": "custom-npm-xxx",
    "dependencies": {
        "express": "^4.17.1",
        "lodash": "^4.17.21"
    }
    //...
}

devDependencies:

• 作用： 开发环境依赖项，仅在开发过程中需要的包,生产环境下是不会安装 devDependencies 字段下的依赖的。
• 注意事项： 通常包含测试框架、打包工具等。

{
    "name": "custom-npm-xxx",
    "devDependencies": {
        "eslint": "^7.32.0",
        "mocha": "^9.1.3"
    }
    //...
}

peerDependencies:

• 作用： 当开发一些插件和工具包时，对使用方的运行环境的依赖包版本有要求，可以使用 peerDependencies 字段进行声明。
• 注意事项： peerDependencies 在 npm 包的依赖关系处理中，很重要。

//假如UI组件库antd的package.json中， peerDependencies要求使用React 16，那么我们项目的react版本必须是大于或者等于此版本。
{
    "name": "antd",
    "peerDependencies": {
        "react": ">=16.8.0"
    }
    //...
}

scripts:

• 作用： 定义可通过 npm 运行的脚本命令，令在开发、测试、构建和部署等阶段都非常有用。

{
    "name": "custom-npm-xxx",
    "scripts": {
        "dev": "vite --mode dev",
        "build": "run-p type-check \"build-only {@}\" --",
        "preview": "vite preview",
        "test:unit": "vitest",
        "build:test": "vite build --mode dev",
        "build:prod": "vite build --mode prod",
        "type-check": "vue-tsc --build --force",
        "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",
        "format": "prettier --write src/"
    }
    //...
}

description:

• 作用： 对包的简短描述。
• 注意事项： 提供清晰而简洁的说明，帮助他人了解包的功能。

private:

• 作用： 布尔值，指定该包是否是私有的（不应该发布到 npm），这是防止意外发布个人仓库的一种保护方式。
• 注意事项： 默认为 false，仅在不希望该包被误发布时设置为 true。

publishConfig:

• 作用： 定义发布 npm 时，设置相关信息。

// registry 发布的npm私源地址
// access 发布有作用域的包，必须要设置access。
// tag 指定当前版本对应的标签
{
    "name": "custom-npm-xxx",
    "publishConfig": {
        "registry": "http://npm.xxx/repository/",
        "access": "public",
        "tag": "xxx"
    }
    //...
}

keywords:

• 作用： 关键字数组，描述包的特性，便于他人搜索和分类。
• 注意事项： 使用相关的关键词，使得包更容易被发现。

main:

• 作用： 指定包的入口文件。
• 注意事项： 默认情况下是 index.js，但可以根据需要指定其他入口文件。

module:

• 作用： 指定 ES 模块的入口文件。
• 注意事项： 当 type 设置为 “module” 时，指定项目的 ES 模块入口。

types:

• 作用：项目如果是用 TypeScript 写的，则需要 types 字段，对外暴露相关的类型定义。

type:

• 作用： 指定模块的类型，可以是 “module”（ES 模块）或 “commonjs”（CommonJS 模块）。
• 注意事项： 当前 Node.js 支持的模块系统配置。

homepage:

• 作用： 指定包的主页 URL。
• 注意事项： 可以是 GitHub 页面、个人网站等，提供更多关于包的信息和文档。

repository:

• 作用： 指定代码仓库的位置。
• 注意事项： 使用对象格式，包括 type（版本控制系统，如 “git”）和 url（仓库 URL）字段。

{
    "name": "custom-npm-xxx",
    "repository": {
        "type": "git",
        "url": "https://github.com/username/my-project.git"
    }
    //...
}

engines:

• 作用： 指定项目运行所需的 Node.js 版本范围。

// 下面代码，告知node版本需要在0.10.3与15之间，才可以运行当前项目。
// 在不符合条件的环境中运行项目时，控制台会有报错输出。
{
    "name": "custom-npm-xxx",
    "engines": {
        "node": ">=0.10.3 <15"
    }
    //...
}

bugs:

• 作用： 开源项目用于接收 bug 反馈。

{
    "name": "custom-npm-xxx",
    "bugs": {
        "url": "https://xxx",
        "email": "project@xxx.com"
    }
    //...
}

license:

• 作用： 指定包的许可证。
• 注意事项： 指定许可证的缩写或者 URL，表明其他人在使用你的包时需要遵循的规定。

author:

• 作用： 指定包的作者。
• 注意事项： 可以是个人名字或者组织名称。

contributors:

• 作用： 列出对包有贡献的人员列表。
• 注意事项： 使用数组格式，每个条目可以包含 name（姓名）和 email（邮箱）等信息。

files:

• 作用： 指定包发布到 npm 上时包含的文件和目录。
• 注意事项： 使用数组格式，列出相对于 package.json 的路径。

workspaces:

• 作用： 用于配置使用 Yarn 或者 npm 工作区（workspaces）特性的 monorepo（单仓库多包）项目。这种项目结构允许你在一个仓库中管理多个相关的包（如模块、库、应用等），而不需要每个包都拥有自己的独立仓库。
• 使用工作区特性可以简化依赖管理和版本控制，确保所有包使用相同的依赖版本，方便进行统一的构建、测试和发布。

{
    "name": "custom-npm-xxx",
    "version": "1.0.0",
    "private": true,
    "workspaces": ["packages/*"],
    "dependencies": {
        "lodash": "^4.17.21"
    },
    "devDependencies": {
        "eslint": "^7.32.0",
        "mocha": "^9.1.3"
    }
    //...
}

cpu:

• 作用： CPU 的要求声明。

{
    "name": "custom-npm-xxx",
    "cpu": ["x64", "ia32"]
    //...
}

os:

• 作用： 操作系统的要求声明。

{
    "name": "custom-npm-xxx",
    "os": ["darwin", "linux"]
    //...
}

npm docs参考