什么是什么？ - Package.json 速查表

基础知识

信息

文件

任务

依赖项

平台

出版

自定义字段

就这样！

AWS GenAI 直播！

这篇文章取自我的博客，所以一定要查看它以获取更多最新内容😉

最近我开始了一个关于 Node.js及其内置 API 的系列文章。正如我所说，我们将深入探讨每一个 Node.js API（至少计划如此）。但是，如果在谈论 Node.js 时不提及著名的package.json 🗄，那就表明我们完全不了解这个文件的重要性。

我想我们都知道 package.json 是什么。几乎每个新的 JS 项目都是从设置这个特定的文件开始的。然而，开发者对这个看似简单却重要的 JSON 文件的了解往往仅限于几个字段。当然，这本身并没有错——你不必了解整个规范，但至少对它有所了解总是好的。这在创建你的第一个公共 NPM 包时尤其重要。👶 而且，由于网络上关于它的文档不一致、不完整或难以阅读，许多新手经常发布他们的第一个包……却总是出错。🚫

综上所述，在本文​​中，我们将最终修复这个缺陷。我们将尽可能深入地探索 package.json！所以，不妨将此页面收藏起来🔖，以便以后作为完整的package.json 速查表使用！📋 开始吧！

基础知识

姓名

我认为这个name属性无需解释。如果没有这个必填字段，你的包将无法正常运行。在命名新包时，你只需要遵循一些规则：

• 您的名字应该是唯一的（发布到 NPM 时）☝；
• 如果您有适当的 NPM 组织注册表，您可以使用具有所谓范围的包，例如 @organization/package；
• 名称的字符长度（包括范围）不应大于214 个字符；
• 开头不能有大写字母和下划线（_）或点（.）；
• 您只能使用URL 安全字符- 您的名字很可能会被其他人在终端中输入并用作 NPM 页面上的 URL；

版本

第二个必需且无需思考的字段。version与 name 一起为您的软件包的每个版本形成一个唯一的 ID 。因为，猜猜怎么着！-您应该/必须随软件包的每个新版本更改版本！此外，您的版本字符串应该可以通过node-semver解析，这意味着它应该具有一定的可预测结构。🏗 您现在应该已经浏览了 NPM，看到了所有可能的版本代码。通常，它以 3 个数字的形式出现，用点 (.) 分隔，例如0.0.0。之后，可选标签（例如next，beta，alpha）前面是破折号，后面可选地跟着另一个点和数字，例如0.0.0-next.0 。当然，您不应该删除任何您认为合适的新版本（尤其是当您的包被其他人使用时）。这就是创建语义版本控制等版本控制指南的原因。

信息

描述

最好向用户提供一些关于你的软件包的信息description。ℹ主 JSON 文件中的一个简短字符串就能很好地实现这个目的！它会显示在NPM 列表和VS Code 弹出窗口中。当然，这还不够，所以在项目根目录下添加README.md文件是个好主意。提到的文件稍后可以用于你软件包的NPM 页面。

关键词

keywords为您提供了改进软件包“SEO”的选项。😅当您的潜在用户使用与您提供的关键词相同的关键词搜索 NPM 列表时，此字符串数组将使您的软件包排名更高。

执照

license是一个简短但非常重要的字段。它能让用户了解您以何种条款共享代码。该字符串必须是SPDX 标识符（简称）之一，例如MIT、GPL-3.0等。如果您还不确定哪种许可证最适合您，可以考虑查看此页面，在这里您可以快速了解并选择最佳许可证（包含 SPDX 标识符！）。建议您稍后将所选许可证的实际文本放在项目根目录的LICENSE.md文件中，这是一个很好的做法（即使不是必需的）。📝

主页

如果你的软件包有一个漂亮的落地页，你可以随意把它的URL放在这里。它稍后会显示在 NPM 页面和其他各种地方。

存储库

如果您在 NPM 上公开发布软件包，那么它很有可能是某种开源软件。因此，关于实际源代码📦的位置信息可能会派上用场。该repository字段就可以做到这一点！您可以通过两种方式设置它 - 一个具有 2 或 3 个属性的对象type，即（您的存储库类型，例如字符串中的“git”或“svn”url ）， （存储库的 URL）以及directory存储库中的可选属性（例如，如果是monorepo）。另一种可能的形式是字符串（也可用于直接从存储库安装软件包），格式为“提供程序:用户/存储库”（其中提供程序可以是“github”、“gitlab”或“bitbucket”）或“ gist : id ”（仅适用于 Gists）。

错误

是的，bugs这种情况经常发生，所以它们值得拥有自己的单独领域。😅 它通常应该指向你的存储库的问题页面或任何其他可以报告这些问题的地方。

作者

该软件包的首位创建者理应获得应有的认可。👌 此字段可以包含两种类型的值：对象或字符串。对象可以包含 3 个属性 - name、email和url（用于作者的网站）。另一种更短的格式是字符串版本，其预定义格式（与对象相比）为“ name < email > ( url ) ”。这些不同的括号是必需的，但并非全部都需要提供。您可以省略例如 (url) 并仅提供 name 和 email。NPM 会接受任何变体。

贡献者

contributors与作者本人一样重要。👬 而且，正如每个作者都应该注意的那样，它还有一个特殊的属性！contributors是一个对象或字符串数​​组，其规则与单个 author 字段相同。另一个有趣的特性是，您可以在项目根目录下提供适当的AUTHORS.md文件，其中将逐行提供项目的贡献者信息（采用前面提到的字符串格式）。这稍后将用作贡献者的默认值。

文件

文件

您很可能希望最终的软件包只包含某些特定文件。为此，您有两个选择。您可以在 package.json 中提供一个属性，以字符串数组files的形式（支持单独的文件、目录和通配符🌟），用于在发送到 NPM 的软件包中仅包含某些特定文件。另一个选择是提供.npmignore文件（例如流行的.gitignore），该文件稍后将用于排除某些文件。当然，有些文件永远不会遵守这些规则，它们将始终被包含（例如README.md或LICENSE.md）或排除（例如node_modules或.git）。

主要的

想必大家都知道这个main字段。它应该指向 default，即整个包中最重要的文件（入口点files）。无论配置如何，它都会被包含在最终的 bundle 中。

浏览器

通过browser属性，我们可以获取包中主文件的不同变体。例如，当您使用某种输出不同格式（例如IIFE或UMD）的模块打包器时，可以使用它。浏览器字段应该指向可在浏览器中使用的文件🖥，并且依赖于该环境的全局变量（例如window）。

解包

也许它并非 100% 官方认可，但UNPKG作为基于 NPM 的 CDN已经获得了如此高的人气和用户群，因此这个属性可能值得仔细研究。unpkg应该指向一个文件，该文件稍后将由 UNPKG 专门用于提供其 CDN 支持。它通常与前面提到的 相同browser。

模块

如果你有的话，module属性应该指出该文件是你的模块化（非捆绑）代码库的入口点。它面向更现代的环境。🚝

打字

typingsor （更短的替代）字段types真正体现了TypeScript及其提供的优秀开发工具的流行程度。此属性应该指向TypeScript 声明文件的入口文件（如果有的话）。该文件稍后会被发送到 NPM，可供下载，并为用户提供良好的IDE 支持。至少在我看来，这比单独将 TypeScript 代码上传到DefinitelyTyped之类的工具要方便一些。

垃圾桶

如果你的包是某种可执行文件，则必须包含此字段。它应该指向Node.js 可执行文件的主文件，或者采用对象的形式，其中键对应于不同的可执行文件，值对应于它们的文件。只需记住，你的可执行文件应该以这行神奇的 ✨ - 开头。#!/usr/bin/env node

男人

如果您有任何软件包的手册页文档，请随时在此处提供。它可以是指向单个文件的字符串，也可以是指向单个文件的数组。

目录

directories可能是那些神秘字段之一，很多人不知道它到底有什么用。🤔 我来告诉你——它主要只是元信息。只有两个字段提供了一些功能，没有其他用途。当然，它们都应该以字符串的形式指向不同的目录。

• lib- 关于您的库在您的包中的确切位置的元信息；
• bin- 所有可执行文件所在的目录。可以使用 属性，而不必逐个提供不同的文件bin。请注意，这两个属性不能同时使用 -只能使用其中一个；
• man- 所有手册页所在的目录。您可以使用它来代替通过属性提供文件数组man。这当然没那么繁琐；
• doc- 有关给定包的Markdown 文档所在目录的元信息；
• example- 有关示例代码目录的元信息；
• test- 有关测试文件所在目录的元信息；

请记住，正如NPM 官方文档所提到的，这些数据将来可以用来提供一些附加功能，例如出色的文档或其他...

任务

脚本

我想你很清楚scripts字段的作用。它是一个简单的对象，其键对应于命令，值对应于它们应该执行的操作。你很可能使用像“build”或“start”这样的脚本名称，但你是否知道有些脚本会在预定义事件发生时自动执行？有很多这样的脚本，你可以在这里找到完整的列表。👈

配置

config属性是一种特殊对象的形式，你可以在其中指定一些稍后可在脚本中使用的配置。👨‍💻例如，名为 的配置属性稍后可以使用 引用，其中前面的部分始终是必需的。这些选项也可以使用 进行更改，例如。portnpm_package_config_portnpm config set [package]:[prop] [value]

依赖项

依赖项

每个人都知道NPM 依赖是什么，以及……关于它们能有多深的梗。😅 并且是一个负责所有这些的字段。这里必须列出你的软件包需要安装（并且最有可能使用）的所有依赖项。或者会自动为你管理这些依赖项。只需记住，你还可以从URL、Git URL、GitHub URL、链接的软件包和本地路径列出并安装依赖项。dependenciesnpm installyarn add

开发依赖项

开发依赖项（使用--save-dev或安装的依赖项--dev）旨在包含给定软件包在开发过程中🏗所需的所有依赖项。例如，它可以是测试框架、模块捆绑器或转译器。所有这些依赖项都不会在软件包的标准使用中安装。

peerDependencies

对等依赖项（这次不会自动配置）允许您指定您的软件包与其他软件包的兼容性。这应该是一个对象的形式，以兼容软件包的名称作为键，以它们各自的版本号（遵循 node-semver，例如 0.xx）作为值。从 NPM v3 开始，这些依赖项默认不安装。

可选依赖项

如果您的软件包是可选的，即并非必须安装但可能有用，您可以在此处添加它们。这些软件包仅在可能的情况下才会安装（例如，如果平台兼容）。常见的例子是名为fsevents的 NPM 模块，它仅在 Mac OS 上可用。

捆绑依赖项

捆绑依赖项应采用数组形式，其中包含将与最终软件包捆绑在一起的依赖项的名称。这在使用 tarball 文件保存项目时非常有用，因为使用tarball 文件npm pack捆绑时会包含此处指定的文件。📦

平台

发动机

engines是一个非常有用的属性（就像其他属性一样），允许你指定一个包含库和运行时（例如Node.js、NPM或React Native ）的对象。对象的键对应于特定的名称（就像 NPM 上的键一样 - 小写，带虚线）和兼容版本字符串（node-semver-compatible）形式的值。当你的包依赖于现代功能（仅在最新的 Node.js 版本中可用）或其他通常全局安装的库和运行时时，这尤其有用。

操作系统

如果您的软件包只能在特定的操作系统上运行，您可以使用属性来指定这一点，其形式为操作系统代码名称os数组。您可以指定仅允许的操作系统（例如），也可以指定不允许的操作系统（例如）。["linux"]["!win32"]

中央处理器

与 类似os，通过使用cpu属性，您可以指定代码可以在哪些类型的 CPU 上运行。同样的规则（包含和排除）也适用（例如["x64"]或["!arm"]）。

出版

私人的

如果您希望您的包保持私密（或将其作为多仓库的入口），可以将此private属性设置为true。这将确保您的包不会被发布，即使您犯了错误并尝试发布。默认情况下，该属性为 false。🔒

发布配置

如果您愿意（或者有其他理由），您可以在发布包之前使用此特定属性覆盖众多NPM 配置值。该属性应为对象形式。您很可能只想更改"tag"、"registry"或 之类的值"access"。

自定义字段

除了上述所有字段之外，package.json 还成为了各种工具放置自定义字段和配置的地方。正如之前提到的， UNPKG、Babel、Prettier💅以及许多其他工具都允许你这样做。这些工具的文档中几乎都有说明。但是，由于工具数量如此之多，package.json 变得有点……拥挤。👎 因此，在我看来，最好尽可能使用单独的配置文件，并将 package.json 仅用于上面列出的所有（仍然很多）内容。

就这样！

我真心希望这篇文章能帮助你们发布你们的第一个公共软件包，或者让你们学到一些新东西。🌟 这是我几周前就希望自己掌握的知识。😅 看了这篇文章，即使是我这个作家，也加深了对 package.json 内容的理解。

和往常一样，请在评论区写下你对这篇文章的看法，并在下方留下你的感想！这给了我很大的激励！另外，你也可以关注我的 推特、脸书页面以及我的个人博客，以便及时了解最新内容。当然，感谢你的阅读，下期再见！