package.json
选择命令行版本:
See Details
目录
描述
¥Description
本文档是你需要了解的关于 package.json 文件中所需内容的全部内容。它必须是实际的 JSON,而不仅仅是 JavaScript 对象字面量。
¥This document is all you need to know about what's required in your package.json file. It must be actual JSON, not just a JavaScript object literal.
本文档中描述的许多行为受到 config
中描述的配置设置的影响。
¥A lot of the behavior described in this document is affected by the config settings described in config
.
name
如果你打算发布你的包,你 package.json 中最重要的就是名称和版本字段,因为它们是必需的。名称和版本共同构成一个假定完全唯一的标识符。对包的更改应该与版本的更改一起出现。如果你不打算发布你的包,名称和版本字段是可选的。
¥If you plan to publish your package, the most important things in your package.json are the name and version fields as they will be required. The name and version together form an identifier that is assumed to be completely unique. Changes to the package should come along with changes to the version. If you don't plan to publish your package, the name and version fields are optional.
名字就是你的东西的名字。
¥The name is what your thing is called.
一些规则:
¥Some rules:
-
名称必须少于或等于 214 个字符。这包括范围包的范围。
¥The name must be less than or equal to 214 characters. This includes the scope for scoped packages.
-
范围包的名称可以以点或下划线开头。没有范围是不允许的。
¥The names of scoped packages can begin with a dot or an underscore. This is not permitted without a scope.
-
新包的名称中不得包含大写字母。
¥New packages must not have uppercase letters in the name.
-
该名称最终成为 URL、命令行参数和文件夹名称的一部分。因此,名称不能包含任何非 URL 安全字符。
¥The name ends up being part of a URL, an argument on the command line, and a folder name. Therefore, the name can't contain any non-URL-safe characters.
一些 技巧:
¥Some tips:
-
不要使用与核心 Node 模块相同的名称。
¥Don't use the same name as a core Node module.
-
不要在名称中添加 "js" 或 "node"。假设它是 js,因为你正在编写 package.json 文件,并且你可以使用“engines”字段指定引擎。(见下文。)
¥Don't put "js" or "node" in the name. It's assumed that it's js, since you're writing a package.json file, and you can specify the engine using the "engines" field. (See below.)
-
该名称可能会作为参数传递给 require(),所以它应该是简短的,但也是合理的描述性的。
¥The name will probably be passed as an argument to require(), so it should be something short, but also reasonably descriptive.
-
你可能需要检查 npm 注册表以查看是否已经存在该名称的内容,然后再过分依赖它。https://www.npmjs.com/
¥You may want to check the npm registry to see if there's something by that name already, before you get too attached to it. https://www.npmjs.com/
名称可以选择以范围为前缀,例如 @npm/example
。有关详细信息,请参见 scope
。
¥A name can be optionally prefixed by a scope, e.g. @npm/example
. See scope
for more detail.
version
如果你打算发布你的包,你 package.json 中最重要的就是名称和版本字段,因为它们是必需的。名称和版本共同构成一个假定完全唯一的标识符。对包的更改应该与版本的更改一起出现。如果你不打算发布你的包,名称和版本字段是可选的。
¥If you plan to publish your package, the most important things in your package.json are the name and version fields as they will be required. The name and version together form an identifier that is assumed to be completely unique. Changes to the package should come along with changes to the version. If you don't plan to publish your package, the name and version fields are optional.
版本必须是 node-semver 可解析的,它与 npm 作为依赖打包在一起。(npm install semver
自己用。)
¥Version must be parseable by node-semver, which is bundled with npm as a dependency. (npm install semver
to use it yourself.)
description
在里面放一段描述。这是一个字符串。这有助于人们发现你的包,因为它在 npm search
中列出。
¥Put a description in it. It's a string. This helps people discover your package, as it's listed in npm search
.
keywords
把关键字放在里面。它是一个字符串数组。这有助于人们发现你的包,因 为它在 npm search
中列出。
¥Put keywords in it. It's an array of strings. This helps people discover your package as it's listed in npm search
.
homepage
项目主页的 URL。
¥The URL to the project homepage.
示例:
¥Example:
"homepage": "https://github.com/npm/example#readme"
bugs
项目问题跟踪器的 URL 和/或应向其报告问题的电子邮件地址。这些对于遇到你的包问题的人很有帮助。
¥The URL to your project's issue tracker and / or the email address to which issues should be reported. These are helpful for people who encounter issues with your package.
它应该如下所示:
¥It should look like this:
{"bugs": {"url": "https://github.com/npm/example/issues","email": "example@npmjs.com"}}
你可以指定一个或两个值。如果你只想提供 URL,则可以将 "bugs" 的值指定为简单字符串而不是对象。
¥You can specify either one or both values. If you want to provide only a URL, you can specify the value for "bugs" as a simple string instead of an object.
如果提供了 URL,npm bugs
命令将使用该 URL。
¥If a URL is provided, it will be used by the npm bugs
command.
license
你应该为你的包指定一个许可证,以便人们知道他们如何被允许使用它,以及你对其施加的任何限制。
¥You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it.
如果你使用的是 BSD-2-Clause 或 MIT 等通用许可证,请为你正在使用的许可证添加当前的 SPDX 许可证标识符,如下所示:
¥If you're using a common license such as BSD-2-Clause or MIT, add a current SPDX license identifier for the license you're using, like this:
{"license": "BSD-3-Clause"}
你可以检查 SPDX 许可证 ID 的完整列表。理想情况下,你应该选择一个 OSI 批准的版本。
¥You can check the full list of SPDX license IDs. Ideally, you should pick one that is OSI approved.
如果你的包在多个通用许可下获得许可,请使用 SPDX 许可证表达式语法版本 2.0 字符串,如下所示:
¥If your package is licensed under multiple common licenses, use an SPDX license expression syntax version 2.0 string, like this:
{"license": "(ISC OR GPL-3.0)"}
如果你使用的许可证尚未分配 SPDX 标识符,或者如果你使用的是自定义许可证,请使用如下字符串值:
¥If you are using a license that hasn't been assigned an SPDX identifier, or if you are using a custom license, use a string value like this one:
{"license": "SEE LICENSE IN <filename>"}
然后在包的顶层包含一个名为 <filename>
的文件。
¥Then include a file named <filename>
at the top level of the package.
一些旧包使用许可证对象或包含许可证对象数组的 "licenses" 属性:
¥Some old packages used license objects or a "licenses" property containing an array of license objects:
// Not valid metadata{"license" : {"type" : "ISC","url" : "https://opensource.org/licenses/ISC"}}// Not valid metadata{"licenses" : [{"type": "MIT","url": "https://www.opensource.org/licenses/mit-license.php"},{"type": "Apache-2.0","url": "https://opensource.org/licenses/apache2.0.php"}]}
这些样式现在已被弃用。相反,请使用 SPDX 表达式,如下所示:
¥Those styles are now deprecated. Instead, use SPDX expressions, like this:
{"license": "ISC"}
{"license": "(MIT OR Apache-2.0)"}
最后,如果你不希望在任何条款下授予他人使用私有或未发布包的权利:
¥Finally, if you do not wish to grant others the right to use a private or unpublished package under any terms:
{"license": "UNLICENSED"}
还可以考虑设置 "private": true
以防止意外发布。
¥Consider also setting "private": true
to prevent accidental publication.
人物字段:作者、贡献者
¥people fields: author, contributors
"author" 是一个人。"contributors" 是一组人。"person" 是具有 "name" 字段以及可选的 "url" 和 "email" 的对象,如下所示:
¥The "author" is one person. "contributors" is an array of people. A "person" is an object with a "name" field and optionally "url" and "email", like this:
{"name": "Barney Rubble","email": "barney@npmjs.com","url": "http://barnyrubble.npmjs.com/"}
或者你可以将所有内容缩短为一个字符串,npm 将为你解析它:
¥Or you can shorten that all into a single string, and npm will parse it for you:
{"author": "Barney Rubble <barney@npmjs.com> (http://barnyrubble.npmjs.com/)"}
email 和 url 都是可选的。
¥Both email and url are optional either way.
npm 还使用你的 npm 用户信息设置顶层 "maintainers" 字段。
¥npm also sets a top-level "maintainers" field with your npm user info.
funding
你可以指定一个包含 URL 的对象,该 URL 提供有关如何帮助资助你的软件包开发的最新信息、字符串 URL 或对象和字符串 URL 的数组:
¥You can specify an object containing a URL that provides up-to-date information about ways to help fund development of your package, a string URL, or an array of objects and string URLs:
{"funding": {"type": "individual","url": "http://npmjs.com/donate"}}
{"funding": {"type": "patreon","url": "https://www.patreon.com/user"}}
{"funding": "http://npmjs.com/donate"}
{"funding": [{"type": "individual","url": "http://npmjs.com/donate"},"http://npmjs.com/donate-also",{"type": "patreon","url": "https://www.patreon.com/user"}]}
用户可以使用 npm fund
子命令列出其项目的所有依赖的 funding
URL,直接和间接。提供项目名称时,还可以使用快捷方式访问每个资助 URL,例如:npm fund <projectname>
(当有多个 URL 时,将访问第一个)
¥Users can use the npm fund
subcommand to list the funding
URLs of all dependencies of their project, direct and indirect. A shortcut to visit each funding URL is also available when providing the project name such as: npm fund <projectname>
(when there are multiple URLs, the first one will be visited)