向npm仓库提交自己的包（译自官方文档）

雮尘
1,394 阅读14分钟

原文连接

创建一个package.json文件

你可以在你的包中加入package.json文件以便其他人管理和安装。

提交到注册中心的包必须含有一个package.json文件。

package.json文件的作用：

  • 列出你项目所依赖的包

  • 可以通过语义化版本规则指定你的项目可以使用的包的版本

  • 使您的构建可重复，因此更容易与其他开发人员共享

提示: 为了使您的包更容易在 npm 网站上找到，我们建议在 package.json 文件中加入description字段。

package.json字段

必须包含name和version字段

一个package.json文件必须包含"name"和"version"字段。

"name"字段表示你的包名，必须是全小写字符，可以包括"-"和"_"。

"version"字段必须是x.x.x的格式，并且遵循语义化版本规则

Author字段

如果你想在包中加入作者信息，可以使用"author"字段，使用如下格式（邮箱和网站是可选的）：

Your Name <email@example.com> (http://example.com)

例子

{
  "name": "my-awesome-package",
  "version": "1.0.0"
}

创建一个新的package.json文件

你可以通过CLI问卷或默认方式创建package.json。

运行CLI问卷

向要通过填写字段的方式创建package.json文件，使用npm init命令。

  1. 在命令行中，跳转到你的包根目录。

    cd /path/to/package

  2. 运行下面的命令：

    npm init

  3. 回答命令行问卷中的问题。

自定义package.json问卷

如果您希望创建许多package.json文件，那么可以自定义init过程中创建的问题和字段，这样所有 package.json 文件都包含一组标准信息。

  1. 在你的主目录中，创建一个名为.npm-init.js的文件。

  2. 添加自定义问题，使用prompt函数：

    module.exports = prompt("what's your favorite flavor of ice cream, buddy?", "I LIKE THEM ALL");

  3. 添加自定义字段，直接向.npm-init.js文件添加要自定义的字段：

    module.exports = {
  customField: 'Example custom field',
  otherCustomField: 'This example field is really cool'
}

    有关详细的npm init自定义配置，请在GitHub上查阅init-package-json

创建默认package.json文件

要使用从工作目录中提取的信息创建的默认 package.json文件，可以使用 npm init命令加上--yes 或-y标志。有关默认值的列表，请参见Default values extracted from the current directory。

  1. 在命令行中，跳转到你的包根目录。

    cd /path/to/package

  2. 运行下面的命令：

    npm init --yes

例子

> npm init --yes
Wrote to /home/monatheoctocat/my_package/package.json:

{
  "name": "my_package",
  "description": "",
  "version": "1.0.0",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/monatheoctocat/my_package.git"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/monatheoctocat/my_package/issues"
  },
  "homepage": "https://github.com/monatheoctocat/my_package"
}
从当前工作目录中提取的默认值
  • name: 当前工作目录的名字
  • version: 总是 1.0.0
  • description: 来自README的信息, 或者是""
  • scripts: 默认会创建 一条test 脚本命令
  • keywords: 空
  • author: 空
  • license: ISC
  • bugs: 当前工作目录的信息，如果有
  • homepage: 当前工作目录的信息，如果有

为init命令设置配置选项

可以为 init 命令设置默认配置选项。例如，要在命令行中设置默认的作者邮箱、作者姓名和许可证，请运行以下命令:

> npm set init.author.email "example-user@example.com"
> npm set init.author.name "example_user"
> npm set init.license "MIT"

创建Node.js模块

Node.js模块是一种可以发布到npm的包。

概览

  1. 创建一个package.json文件

  2. 创建当另一个应用程序引入你的模块时会加载的文件

  3. 测试你的模块

创建一个package.json文件

  1. 为创建package.json文件，在命令行中，在node.js模块的根目录下，运行npm init：

  2. 为所需的字段(name和version)以及main字段提供内容：

    • name：模块名称

    • version：模块的初始版本号，我们推荐遵循语义化版本规则设置为1.0.0

创建当另一个应用程序引入你的模块时会加载的文件

在文件中，添加一个函数作为export对象的属性。这将使这个函数能被其它代码使用。

exports.printMsg = function() {
  console.log("This is a message from the demo package");
}

测试你的模块

  1. 将你的包发布到npm

  2. 在命令行中，在项目目录之外创建一个新的测试目录。

    mkdir test-directory

  3. 切换到新的目录：

    cd /path/to/test-directory

  4. 在测试目录中，安装你的模块：

    npm install <your-module-name>

  5. 在测试目录中，创建test.js文件用来引入你的模块并调用里面的方法。

  6. 在命令行中，运行node test.js，console.log中的内容就会显示出来。

关于包里的README文件

为帮助其它人更好的在npm中找到你的项目，并且在他们项目中使用你的代码时获得好的体验，我们建议你在包目录里面加入README文件。你的README文件可能包含安装、配置、使用包中代码、和其它用户觉得有帮助的信息。README文件的内容会展示在包页面中。

在包中创建并添加README.md文件

  1. 在文本编辑器中，在你的包根目录中，创建一个名为README.md的文件。

  2. 在README.md的文件中，加入关于你包的有效信息。

  3. 保存README.md文件。

提示： .md结尾的文件代表Markdown文件，关于Markdown，可以查看GitHub中的指南："Mastering Markdown"

更新现有包中的README.md文件

只有在发布包的新版本时，README文件才会在包页面上更新。更新README文件:

  1. 在文本编辑器中，更新README.md文件的内容。

  2. 保存README.md文件

  3. 在命令行中，你的包根目录中，运行下面的命令：

    npm version patch
npm publish

创建和发布无范围的公共包

作为 npm 用户，你可以创建在你自己的项目中使用的无范围的包，并将它们发布到 npm 公共注册中心，以供其他人在他们的项目中使用。无作范围包始终是公有的，只能通过包名称引用：

package-name

提示： 有关包范围、访问和可见性的更多信息，请参见"Package scope, access level, and visibility"。

创建无范围的公有包

  1. 在命令行中，给你的包创建一个目录：

    mkdir my-test-package

  2. 切换到你包的根目录中：

    cd my-test-package

  3. 如果你使用 git 来管理你的包代码，在包根目录中，运行以下命令，替换你包的 git remote URL：

    git init
git remote add origin git://git-remote-url

  4. 在包的根目录中， 运行npm init命令。

  5. 根据提示输入内容创建package.json文件。有关帮助你命名包的信息，请参阅 "Package name guidelines"。

  6. 创建一个 README 文件，解释包代码以及如何使用它。

  7. 在你喜欢的文本编辑器中，为你的包编写代码。

检查包内容是否有敏感或不必要的信息

将敏感信息发布到注册中心可能会伤害你的用户，影响你的开发基建工作，修复代价高昂，并且将你置于法律行动的风险之中。我们强烈建议删除敏感信息，比如私钥、密码、个人身份信息和信用卡数据，然后再发布到注册中心。

对于没这么敏感的数据，如测试代码，使用.npmignore或.gitignore文件防止他们被发布到注册中心中。更多信息，请参见本文。

测试你的包

为了减少发布 bug 的机会，我们建议在将包发布到 npm 注册中心之前对其进行测试。要测试你的软件包，运行npm install 加你包目录的完整路径:

npm install my-package

发布无范围的公共包

  1. 在命令行，切换到你的包根目录

    cd /path/to/package

  2. 将你的包发布到npm注册中心，运行：

    npm publish

  3. 要查看你的公共包页面，请访问 npmjs.com/package/*pa… ，用你的包的名称替换package-name * 。公共软件包会在 npm 网站的软件包名称下面写上 public。

有关publish命令的更多信息，请参见 CLI 文档。

创建和发步含有范围的公有包

要在用户或组织命名空间中公开共享代码，可以将公有用户范围或组织范围的包发布到 npm 注册中心。

有关范围的详细信息，请参阅"About scopes"。

注意： 在发布用户范围的npm包之前，必须注册一个npm用户帐户。

此外，要发布组织范围内的包，您必须创建一个 npm 用户帐户，然后创建一个 npm 组织。

创建有范围的公有包

  1. 如果您正在使用npmrc来管理多个注册中心的帐户，在命令行上，切换到适当的配置文件：

    npmrc <profile-name>

  2. 在命令行上，为你的包创建一个目录：

    mkdir my-test-package

  3. 切换到包的根目录:

    cd my-test-package

  4. 如果你使用git来管理包代码，在包根目录中，运行以下命令，替换你包的 git remote URL：

    git init
git remote add origin git://git-remote-url

  5. 在包根目录，运行npm init命令，并将参数传给scope标记：

    • 对于组织范围的包，将my-org 替换为你的组织名称：

      npm init --scope=@my-org

    • 对于用户范围的包，将my-username替换为你的用户名：

      npm init --scope=@my-username

  6. 根据提示输入内容创建package.json文件。有关帮助你命名包的信息，请参阅 "Package name guidelines"。

  7. 创建一个 README 文件，解释包代码以及如何使用它。

  8. 在你喜欢的文本编辑器中，为你的包编写代码。

检查包内容是否有敏感或不必要的信息

将敏感信息发布到注册中心可能会伤害你的用户，影响你的开发基建工作，修复代价高昂，并且将你置于法律行动的风险之中。我们强烈建议删除敏感信息，比如私钥、密码、个人身份信息和信用卡数据，然后再发布到注册中心。

对于没这么敏感的数据，如测试代码，使用.npmignore或.gitignore文件防止他们被发布到注册中心中。更多信息，请参见本文。

测试你的包

为了减少发布 bug 的机会，我们建议在将包发布到 npm 注册中心之前对其进行测试。要测试你的软件包，运行npm install 加你包目录的完整路径:

npm install my-package

发布有范围的公有包

默认情况下，范围包以私有可见性发布。要发布具有公共可见性的作范围，请使用 npm publish --access public。

  1. 在命令行，切换到你的包根目录

       cd /path/to/package

  2. 要将含范围的公共包发布到 npm 注册表，请运行：

    npm publish --access public

  3. 要查看您的公共包页面，请访问 npmjs.com/package/*pa… ，用你的包的名称替换package-name* 。公共软件包会在 npm 网站的软件包名称下面写上public。

Screenshot of a public npm Teams package

有关publish命令的更多信息，请参见 CLI 文档。

创建和发布私有包

步骤和发布公有有范围的包一样，在发布的时候去掉--access即可：

npm publish

发布成功后可以在npm中看到你的包

Screenshot of a private npm Teams package

包命名规范

在为包选择名称时，请遵循如下规则

此外，在为未作用域的包选择名称时，还要遵循

  • 不是已经被别人拥有了

  • 不和其它包名字很像

  • 不会让其他作者混淆

在package.json文件中指定dependencies和devDependencies

要指定项目所依赖的包，必须在包里的package.json文件将它们标记在"dependencies"或"devDependencies"里面，npm 将下载package.json 中列出的dependencies和 devDependencies，每个dependencies和 devDependencies 都要满足语义化版本要求。若要查看将安装哪个版本的包，请使用semver calculator。

  • "dependencies"：应用程序在生产中所需的包。

  • "devDependencies"：仅用于本地开发和测试的包。

添加dependencies到package.json文件

你可以通过命令行或者手动编辑package.json文件的方式添加dependencies。

通过命令行方式添加dependencies到package.json

要从命令行将dependencies和devDependencies添加到package.json文件，可以给npm install命令添加--save-prod标记来添加dependencies（默认添加），或者通添加--save-dev标记添加devDependencies。

要在命令行中为 package.json文件的"dependencies"属性添加一个条目，请运行以下命令：

npm install <package-name> [--save-prod]

要在命令行中为 package.json文件的"devDependencies"属性添加一个条目，请运行以下命令：

npm install <package-name> --save-dev

手动编辑package.json文件

要在文本编辑器中向package.json文件添加依赖项，需要添加一个名为"dependencies"的属性，该属性注明每个依赖项的名称和语义化版本：

{
  "name": "my_package",
  "version": "1.0.0",
  "dependencies": {
    "my_dep": "^1.0.0",
    "another_dep": "~2.2.0"
  }
}

要在package.json文件中添加devDependencies，需要在文本编辑器中，添加一个名为"devDependencies"的属性，该属性注明每个devDependencies的名称和语义化版本：

"name": "my_package",
"version": "1.0.0",
"dependencies": {
  "my_dep": "^1.0.0",
  "another_dep": "~2.2.0"
},
"devDependencies" : {
  "my_test_framework": "^3.1.0".
  "another_dev_dep": "1.0.0 - 1.2.0"
}

关于语义化版本

为了保持 JavaScript 生态系统的健康、可靠和安全，每次对自己拥有的 npm 包进行重大更新时，我们建议在遵循语义版本规范的 package.json 文件中发布一个包的新版本，其中包含更新后的版本号。遵循语义版本管理规范可以帮助依赖于你的代码的其他开发人员理解给定版本中的更改程度，并在必要时调整自己的代码。

注意： 如果您引入的更改打破了包依赖关系，我们强烈建议增加版本主编号; 详情见下文。

在已发布的包中增加语义版本

为了帮助依赖你的代码的开发人员，我们建议你从1.0.0开始使用包版本，并按以下步骤递增：

代码状态阶段规则示例版本号
首次发布新产品从1.0.0开始1.0.0
向后兼容的bug修复补丁版本增加第三位数字1.0.1
向后兼容的新功能次要版本增加中间数字并将最后一个数字复位为零1.1.0
打破向后兼容性的变化主要版本增加第一个数字并将中间和最后一个数字重置为零2.0.0

修改版本号的命令：

// 更新补丁版本
npm version patch
// 更新次要版本
npm version minor
// 更新主版本号
npm version major

使用语义版本控制来指定包可以接受的更新类型

您可以在包的 package.json 文件中指定包可以从依赖项接受哪些更新类型。

例如，要指定可接受的版本范围到1.0.4，使用以下语法:

  • 补丁版本: 1.0 或 1.0.x 或 ~1.0.4
  • 次要版本: 1 或 1.x 或 ^1.0.4
  • 主要版本: * 或 x

有关语义版本控制语法的详细信息，请参阅 npm semver calculator。

例子

"dependencies": {
  "my_dep": "^1.0.0",
  "another_dep": "~2.2.0"
},

资源

www.youtube.com/watch?v=kK4…

添加dist-tags到包中

发布标签(dist-tags)是人们可读的标签，你可以使用它来组织和标记发布的不同版本的包。

dist-tags支持语义化版本。除了比语义版本编号更具人性化可读性之外，标签还允许发布者更有效地分发他们的包。

有关更多信息，请参见 dist-tag CLI 文档。

注意： 因为 dist-tags 与语义版本共享一个名称空间，所以要避免dist-tags与现有版本号发生冲突。我们建议避免以数字或字母"v"开头的dist-tags。

发布一个带有dist-tag的包

默认情况下，运行npm publish 将使用latest dist-tag 标记你的包。若要使用另一个 dist-tag，请在发布时使用 --tag 标志。

  1. 在命令行，切换到你的包的根目录：        

    cd /path/to/package

  2. 运行如下命令，将<tag>替换为你想要使用的tag：

    npm publish --tag <tag>

例子

要在命令行上发布带有"beta"dist-tag的包，请在包的根目录中运行以下命令:

npm publish --tag beta

向特定版本的包添加dist-tag

  1. 在命令行，切换到你的包的根目录：

      cd /path/to/package

  2. 运行以下命令，将<package_name>替换为包的名称，将 <version>替换为包的版本号，将<tag>替换为分发标记：

    npm dist-tag add <package-name>@<version> [<tag>]

例子

要将"stable"标记添加到1.4.0版本的"example-package"包中，你可以运行以下命令:

npm dist-tag add example-package@1.4.0 stable
avatar
文章
阅读
粉丝