developers

开发者指南

选择 CLI 版本：

Table of contents

描述

因此，你决定使用 npm 来开发（并且可能发布/部署）你的项目。

极好的！

在用户安装程序的简单步骤之外，你需要做一些事情。

关于这些文件

这些是手册页。如果你安装了 npm，你应该能够执行 man npm-thing 来获取有关特定主题的文档，或者执行 npm help thing 来查看相同的信息。

什么是包

一个包是：

a) 包含由 package.json 文件描述的程序的文件夹
b) 一个 gzipped tarball，包含 (a)
c) 解析为 (b) 的 url
d) 在注册表上发布的 <name>@<version> (c)
e) 指向 (d) 的 <name>@<tag>
f) 具有满足 (e) 的 "latest" 标签的 <name>
g) 一个 git url，在克隆时会导致 (a)。

即使你从不发布你的包，如果你只是想写一个 node 程序（a），你仍然可以获得使用 npm 的很多好处，也许你还想在打包后能够轻松地安装它成一个 tarball (b)。

Git url 可以是以下形式：


git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish

commit-ish 可以是可以作为参数提供给 git checkout 的任何标记、sha 或分支。默认值为 master。

package.json 文件

你需要在项目的根目录中有一个 package.json 文件才能使用 npm 执行大部分操作。这基本上是整个界面。

有关该文件中内容的详细信息，请参见 package.json。至少，你需要：

name: 这应该是一个标识你的项目的字符串。请不要使用名称来指定它在 node 上运行，或者在 JavaScript 中。你可以使用 "engines" 字段来明确说明程序所需的 node 版本（或其他任何版本），并且可以很好地假设它是 JavaScript。
它不一定需要与你的 github 存储库名称匹配。
所以，node-foo 和 bar-js 是坏名字。 foo 或 bar 更好。
version: 与 semver 兼容的版本。
engines: 指定程序运行的 node（或其他）版本。 Node API 变化很大，可能存在你依赖的错误或新功能。明确。
author: 拿点信用。
scripts: 如果你有一个特殊的编译或安装脚本，那么你应该把它放在 scripts 对象中。你绝对应该至少有一个基本的烟雾测试命令作为 "scripts.test" 字段。见脚本。
main: 如果你有一个模块作为程序的入口点（就像 "foo" 包在 require("foo") 处给你的那样），那么你需要在 "main" 字段中指定它。
directories: 这是一个将名称映射到文件夹的对象。最好包括 "lib" 和 "doc"，但如果你使用 "man" 指定一个充满手册页的文件夹，它们将像这些一样被安装。

你可以在包的根目录中使用 npm init，以便开始使用非常基本的 package.json 文件。有关详细信息，请参阅 npm init。

将文件保存在你的包之外

使用 .npmignore 文件将内容保存在你的包之外。如果没有 .npmignore 文件，但有 .gitignore 文件，则 npm 将忽略 .gitignore 文件匹配的内容。如果要包含 .gitignore 文件排除的内容，可以创建一个空的 .npmignore 文件来覆盖它。与 git 一样，npm 在包的所有子目录中查找 .npmignore 和 .gitignore 文件，而不仅仅是根目录。

.npmignore 文件跟随相同的模式规则为 .gitignore 文件：

空白行或以 # 开头的行将被忽略。
标准 glob 模式有效。
你可以使用正斜杠 / 结束模式以指定目录。
你可以通过以感叹号 ! 开头来否定模式。

默认情况下，会忽略以下路径和文件，因此无需将它们显式添加到 .npmignore：

.*.swp
._*
.DS_Store
.git
.hg
.npmrc
.lock-wscript
.svn
.wafpickle-*
config.gypi
CVS
npm-debug.log

此外，node_modules 中的所有内容都将被忽略，但打包的依赖除外。 npm 会自动为你处理此问题，因此不必费心将 node_modules 添加到 .npmignore。

以下路径和文件永远不会被忽略，因此将它们添加到 .npmignore 是没有意义的：

package.json
README （及其变体）
CHANGELOG （及其变体）
LICENSE / LICENCE

如果在给定项目结构的情况下，你发现 .npmignore 是一个令人头疼的维护问题，你可以尝试填充 package.json 的 files 属性，该属性是应该包含在你的包中的文件或目录名称的数组。有时白名单比黑名单更容易管理。

测试你的 `.npmignore` 或 `files` 配置是否有效

如果你想仔细检查你的包在发布时是否只包含你想要的文件，你可以在本地运行 npm pack 命令，这将在工作目录中生成一个 tarball，与发布时相同。

链接包

npm link 旨在安装开发包并实时查看更改，而无需不断重新安装。（当然，你确实需要重新链接或 npm rebuild -g 来更新已编译的包。）

更多信息在 npm link。

发布之前：确保你的包安装和工作

这个很重要。

如果你无法在本地安装它，则尝试发布它会遇到问题。或者，更糟糕的是，你可以发布它，但你将发布一个损坏或毫无意义的包。所以不要那样做。

在包的根目录中，执行以下操作：


npm install . -g

这会告诉你它正在工作。如果你只想创建一个指向你的工作目录的符号链接包，请执行以下操作：


npm link

使用 npm ls -g 查看它是否存在。

要测试本地安装，请进入其他文件夹，然后执行以下操作：


cd ../some-other-folder
npm install ../my-package

将其本地安装到其他地方的 node_modules 文件夹中。

然后进入 node-repl，尝试使用 require("my-thing") 来引入你的模块的主模块。

创建用户账户

使用 adduser 命令创建用户。它是这样工作的：


npm adduser

然后按照提示进行操作。

这在 npm adduser 中有更好的记录。

发布你的包

这部分很简单。在文件夹的根目录中，执行以下操作：


npm publish

你可以给发布一个 tarball 的 url，或者一个 tarball 的文件名，或者一个文件夹的路径。

请注意，默认情况下几乎是 该文件夹中的所有内容都会暴露。因此，如果你有秘密内容，请使用 .npmignore 文件列出要忽略的 glob，或从新结帐中发布。

宣传它

在 IRC 中发送电子邮件、写博客、闲聊。

告诉世界安装你的程序是多么容易！