你真的了解package.json吗？

今天我们就来讲讲「package.json」。

还有很多同学说，f_cli[1]啥时候开源。这里简单说一嘴，因为f_cli现在只适配了针对vite+react的模板，然后我想着想把vite+vue/webpack+react/vue/rsPack+vue/react最起码再适配1-2个后，才有开源计划。

1. 什么是package.json

package.json 是JS/TS项目的说明书和指导手册

按照功能来分类，package.json具有如下的功能：(有些功能是可以相互配合使用的)

依赖管理

一个成熟的语言，不仅仅需要在语言层面功能完备，还体现在构建大型项目时是否具有低成本的依赖管理能力。

现在有许多用于依赖管理的工具，比如 Java 的 Maven，Python 的 pip，JavaScript 的 npm/pnpm /yarn，以及 Rust 的 Cargo。

每个包管理器都需要一种方式来跟踪在「当前项目中应该使用哪些版本的哪些软件包」。通常，会创建一个文件，将这些「依赖关系映射到它们对应的版本」上。比如，

• JS项目开发时，在根目录上会存在package.json
• 在Rust项目开发时，根目录下有Cargo.toml

我们今天的主角 -package.json的主要作用是「跟踪项目中所需的所有依赖关系」。当运行 JS 包管理器上的 install 命令时，它将安装在 package.json 文件中提到的软件包的相应版本。

定义命令&执行任务

这点大家都很熟，在现在前端开发中，尤其在SPA模式开发下，我们通常会使用打包工具Vite/Webpack/rsPack分别对开发模式和生产模式进行区分。要想实现上述操作。我们就需要在一个地方定义一些操作:执行命令，并且能够在通过npm cli命令行执行这些「操作」。

而这就是package.json中scripts的用途。我们可以定义很多操作然后执行诸如dev/build/prepare/postinstall等命令。

这个是利用npm的生命周期做一些资源整合的事情。这个我们会另写一篇文章。这里也不再多讲。

存储元数据

在如何在 npm 上发布二进制文件？中，我们同样有package.json，它既不是用于「依赖管理」也不是用于定义项目命令，而是通过一些字段的配置来说明包的名称和版本信息，以及该包被用于那些操作系统和系统架构。

也就是说，

package.json还可以存储必要的包的元数据。

2. package.json 中关键字段

创建package.json

我们可以使用 npm init 命令在任意我们想创建前端项目的文件夹中创建一个 package.json 文件。当我们运行该命令时，它会询问我们一系列的问题，我们输入的所有答案都会显示在我们的 package.json 文件中。

图片

当我们填入我们想要的信息后，就会在项目的根目录下创建一个package.json文件。

{
  "name": "front789",
  "version": "1.0.0",
  "description": "专注于前端开发技术Rust及AI应用知识分享的Coder",
  "main": "index.js",
  "scripts": {
    "test": "vitest"
  },
  "repository": {
    "type": "git",
    "url": "https://xxx/xxx"
  },
  "keywords": ["前端开发", "rust", "ai"],
  "author": "front789 (https://xxx/xx)",
  "license": "MIT"
}

当然我们也可以采用手动方式在项目根目录下创建一个package.json并填入必要的信息

如果大家看过package.json的官网[2]的话，会发现有很多属性，并用它使用场景五花八门。

而今天我们也不打算把这些属性都过一遍，我会有选择的挑选一些对我们平时开发有用的属性来讲。

name

name 字段用于标识软件包。

{
  "name": "my-project"
}

在 package.json 文件中，name和version是「强制」的，它们一起被认为是唯一的。例如，如果name是 f_cli，version是 0.1.0，那么就假定f_cli@0.1.0是唯一的，不指代任何其他软件包。

软件包name也是有一定的限制的。

❝

它需要符合^(?:(?:@(?:[a-z0-9-*~][a-z0-9-*._~]*)?/[a-z0-9-._~])|[a-z0-9-~])[a-z0-9-._~]*$正则规则

❞

• 它不能超过 214 个字符，并且只能包含小写字母。
• 名称不能以点(.)或下划线(_)开头。
• 此外，名称通常是 URL 的一部分，因此必须是 URL 安全的。

软件包名称也可以是作用域(scope)的。例如，软件包的名称可以是@front/f_cli。这是@organization/package 的形式。但是这种形式时候需要花钱的。

如果将包发布到 npmjs，则 name 属性是必需的并且必须是唯一的。如果使用和 npmjs已经存在的名称发布包，将收到错误。

如果不将包发布到npmjs,那么项目的name字段就没有那么多要求。

version

{
  "version": "1.1.0",
}

version 字段也是用于标识软件包的键。通常，此版本号必须是可由 node-semver[3] 解析的。

「语义化版本控制」（Semantic Versioning，SemVer）是一组用于版本控制的规则，以便版本号的更改表明软件包中的变化类型。

版本号以 MAJOR.MINOR.PATCH 的形式编写

• 如果新版本中有错误修复，则增加 PATCH。
• 如果有新功能，则增加版本的 MINOR 部分。
• 如果新版本有破坏性变化或与旧版本不兼容，则增加版本的 MAJOR 部分。

例如，如果软件包的当前版本为 1.0.9：

• 如果下一个发布仅包含错误修复，则新版本应为 1.0.10。
• 如果下一个发布包含新功能，则新版本应为 1.1.0。
• 如果下一个发布有破坏性变化，则新版本应为 2.0.0。

description

description 字段简要描述了「软件包的功能」。它对于 SEO 也很有用，因为它帮助其他人可以在npmjs.com 网站上找到我们的软件包。当用户在npmjs.com搜索包时，此字符串用于帮助显示包。

就像我们f_li_darwin_arm64的包有如下的配置信息。

图片

当我们在npmjs中按照description搜索时也会返回对应的结果。

图片

即使我们没有将其发布到npmjs，它也可以用作项目的说明书,来说明该项目的性质和功能。起到一个「高屋建瓴」的作用。

keywords

{
  "keywords": ["f_cli", "MACOS_Intel64"]
}

keywords 字段是一个「字符串数组」，与 description 类似，keywords 字段也用于 SEO。该字段由 npmjs编制索引，用于帮助在有人搜索包时找到包。数组中的每个值都是与我们的包关联的一个关键字。

图片

如果我们不发布到npmjs，则此字段没有多大用处，可以随意省略它。

homepage

{
  "homepage": "https://github.com/owner/project#readme"
}

通常，我们会在此字段中链接到项目的网站地址。或者，我们还可以指向项目的 README 或文档。

bugs

{
  "bugs": {
    "url": "https://github.com/owner/project/issues",
    "email": "project@hostname.com"
  }
}

当别人使用了我们的包，在遇到问题后可以依据这个字段提供的url和email来提出问题，并尝试在需要的地方寻找解决方案。

如果我们不想提供支持电子邮件，我们可以直接将 URL 分配给 bugs 属性。

{
  "bugs": "https://github.com/owner/project/issues",
}

license

{
  "license":"MIT"
}

license 是一个重要的字段，因为它向使用包的用户描述了我们在使用此软件包时设置的「权限」和「限制」。理想情况下，对于开源软件包，许可证应该是 OSI 批准[4]的许可证之一。

下面是我们常见的OSI软件开源协议。

如果我们不希望在任何条件下向软件包的用户授予任何权限，可以将此字段设置为 UNLICENSED。

如果这个项目是我们公司的项目，并且也不准备开源，应该将 package.json 文件中的 private 字段设置为 true，以防止意外发布软件包。

author

author 字段用于提供有关软件包开发者的信息。它包括一个name，以及一个可选的email和 url 字段。

以下是一个示例：

{
  "name": "front789",
  "email": "xx@gmial.com",
  "url": "https://xx.io"
}

所有这些信息也可以缩小成以下格式的单个字符串：

{
  "author": "Name  (Site)"
}

例如，我们可以使用此格式指定与上述相同的作者：

{
  "author": "front789  (https://xx.io)"
}

contributors

与 author 字段类似，contributors 字段提供有关软件包开发者的信息。它包含一个作者数组。

files

files 字段是一个「文件模式数组」，描述当「我们的包作为依赖项安装时要包含的文件」。

文件模式遵循与.gitignore 类似的语法。唯一的区别是在.gitignore 中指定的文件被排除在外，而这些文件被包括在内。我们还可以使用像*和**/*这样的 glob 模式，就像在.gitignore 文件中一样。

如果未特别指定，则 files 字段默认为["*"]。

我们可以在包的根目录或子目录中提供 .npmignore 文件，这将防止包含文件。 .npmignore 文件的工作方式与 .gitignore 类似。

一些特殊的文件和目录也会被包含，无论它们是否存在于 files 数组中。

• package.json
• README
• LICENSE / LICENCE
• 在main字段指定的文件
• 在bin字段指定的文件

其中README 和 LICENSE/LICENCE 文件可以具有任何扩展名。

main

{
  "main": "src/index.js",
}

main 字段是 package.json 的「功能属性」。这定义了项目的入口点，通常也是用于启动项目的文件。

如果我们的软件包（假设其名称为 front789）由用户安装，那么当用户执行 require('front789') 时,则将返回主模块的导出对象。

这通常是项目根目录中的 index.js 文件，但它可以是我们选择用作包的主入口的任何文件。

如果未设置 main，则默认为包根文件夹中的 index.js

该字段在Node12+有另外的替代方案 - exports。

图片

exports

我们可以使用 exports 字段定义软件包的入口点，作为 main 字段的替代方案。与 main 不同，exports 允许我们定义子路径导出和条件导出。

例如，我们可以使用以下 exports 属性导出项目的 submodule.js 文件：

{
  "exports": {
    ".": "./index.js",
    "./submodule.js": "./src/submodule.js"
  }
}

还可以条件导出 - 具体取决于软件包的使用者是使用 require 还是 import。

{
  "exports": {
    "import": "./index-module.js",
    "require": "./index-require.cjs"
  },
  "type": "module"
}

条件导出通常用于 ESM 软件包，以确保向后兼容性，因为 import 关键字只能在 ESM 中使用。

type

此字段描述了当前软件包中的.js 文件应该被视为 ESM 还是 commonjs。我们可以为 ESM 设置module类型，并为非ESM 软件包设置 commonjs。

此外，我们还可以明确指定文件是否应该解释为 ESM 或 commonjs，使用.mjs 扩展名表示 ESM，.cjs扩展名表示 commonjs 文件。

{
  "type": "module"
}

browser

此字段用于表示软件包是否应在浏览器中使用，而不是在 Node.js 项目中使用，以取代 main。当我们的软件包使用像 window 这样的浏览器API，在 Node.js 环境中不可用时，就会使用它。

bin

这个我们很熟，在如何在 npm 上发布二进制文件？中，我们在定义主包时，就使用了bin字段。

bin 字段，该字段是「命令名」到「本地文件名」的映射。

在某些情况下，npm 软件包需要安装到 PATH 中，以便它们可以在任何目录中直接由操作系统运行。bin 字段指定这些类似可执行文件的文件。

当此软件包「全局安装」时，该文件将链接到全局 bins 目录内，或者将创建一个 cmd（Windows 命令文件）来执行 bin 字段中的指定文件，因此可用于由 name 或 name.cmd（在 Windows PowerShell 上）运行。

当我们在 bin 属性中有以下配置。

{
  "bin": {
    "c1": "./r1.js",
    "c2": "./r2.js"
  }
}

在全局安装此软件包（使用 npm install -g）后，我们将能够直接从终端运行 c1 和 c2 等命令。

• 这在 unix-like 操作系统上内部创建了 r1.js 文件到/usr/local/bin/c1 的符号链接，以及 r2.js 到/usr/local/bin/c2 的符号链接。
• 在 Windows 上，会创建一个 C:\Users\{Username}\AppData\Roaming\npm\c1.cmd 文件，该文件运行 r1 脚本。

bin 属性提到的文件，都以 shebang语法 #!/usr/bin/env node 开头，否则我们的操作系统将不会意识到该文件应在 Node.js 环境中运行。

shebang

shebang是一种在Unix/Linux系统中用于「指定脚本解释器的约定」。在Node.js中，也可以使用shebang来指定Node.js作为脚本的解释器。在脚本文件的开头，添加类似于#!/usr/bin/env node的行，告诉操作系统使用Node.js来解释执行该脚本。

Node.js的shebang行告诉操作系统找到Node.js解释器并使用它来执行脚本。这使得脚本可以作为可执行文件直接运行，而不必在命令行中显式调用Node.js。

案例分析

还记得f_cli的npm版本吗。

我们在package.json中的bin字段定义f_cli_f和bin/cli直接的关系

图片

并且在bin/cli中使用shebang指定node.js作为脚本解释器。

图片

repository

该字段来记录项目代码所在的地址。该字段是一个对象，它定义了源代码所在的 url，以及它使用的版本控制系统类型。对于开源项目，大部分都是GitHub，以 Git 作为版本控制系统。

{
  "repository": {
    "type": "git",
    "url": "https://github.com/xxx/docs.git"
  }
}

scripts

script 字段是 package.json 中另一个「功能性元数据」

scripts 属性是一个包含我们可以使用 npm CLI 运行的脚本命令的「字典」。其键是我们可以使用 npm run  运行的脚本，值是实际运行的命令。这些通常是终端命令，我们将其放入脚本字段中，以便我们可以记录它们并轻松地重用它们。

我们还可以指定在软件包生命周期的不同时间运行的脚本。例如，我们可以添加一个 prepublish 脚本，在软件包发布之前运行（当我们运行 npm publish 时）。

这是一个比较大的主题，我们打算另起一篇，详细介绍一下

dependencies

{
  "dependencies": {
    "A": "^4.16.4",
    "B": "~1.7.4"
  }
}

此处列出了我们的项目使用的所有依赖项。使用 npm cli 安装软件包时(npm install xxx@1.0.1)，会将其下载到我们的 node_modules/ 文件夹中，并将添加到我们的依赖项属性中，并注明软件包的名称(xxx)和安装的版本(1.0.1)。

dependencies字段是一个对象，以包名称作为键，以版本或版本范围作为值。从这个列表中，npm 知道当 npm install 在目录中运行时要获取和安装哪些包（以及什么版本）。 package.json 的 dependency 字段是项目的核心，它定义了项目所需的外部包。

我们在dependencies中看到的脱字号 (^) 和波形符 (~) 是 SemVer[5] 中定义的版本范围的表示法。

在语义版本控制中,版本号由三个数字组成,格式如下:

`主版本号.次版本号.修订号`

• 脱字符号(^)表示允许更新到最新的次版本号:

• ^1.2.3 表示 >=1.2.3 并且 =1.2.3 并且