使用 NPM 发布与维护 TypeScript 模块

2019独角兽企业重金招聘Python工程师标准>>>

本文介绍如何发布一个包到 npmjs.org，包括创建、发布、撤回、更新、使用分支等等，以及其中 包含的一些小技巧。

0. 创建

创建一个包很简单，就是手动或者用 npm init 命令直接生成一个 package.json 文件，一个 包就算是创建出来了。剩下的就是给它添加内容而已了。

如果使用 npm init 命令配合 -y 或者 --yes 参数，可以不使用命令行交互模式，而 快速地创建一个 package.json 文件。

npm init -y

比如我这里创建出来的是：

name 字段默认是当前所在的目录名称。

{
  "name": "test",
  "version": "0.1.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "Angus.Fenying <i.am.x.fenying@gmail.com> (https://fenying.net/)",
  "license": "Apache-2.0"
}

什么，你说你创建出来是下面这样的？有些字段的初始值和我的不一样？

{
  "name": "test",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

别急，那是因为你没有设置 NPM 的一些默认配置。通过下面三条命令，可以设置创建新的 NPM 包时使用的默认属性。

npm config set init-author-name "Angus.Fenying"             # 你的名称
npm config set init-author-email "i.am.x.fenying@gmail.com" # 你的邮箱
npm config set init-author-url "https://fenying.net"        # 你的个人网页
npm config set init-license "Apache-2.0"                    # 开源授权协议名
npm config set init-version "0.1.0"                         # 版本号

1. 准备

现在你可以为 package.json 添加内容了，比如修改如下：

{
  "name": "npm-tutorial-test-1",
  "version": "0.1.0",
  "description": "This is a test package for my NPM tutorial.",
  "main": "index.js",
  "scripts": {
    "test": "echo hello"
  },
  "keywords": [
      "test"
  ],
  "author": "NPM Learner <me@sample.com> (https://sample.com/)",
  "license": "MIT"
}

然后添加一个 README.md 文件，内容如下：

# NPM Tutorial Test 1

This is a test package for my NPM tutorial.

## License

This package is published under [MIT license](./LICENSE).

添加你的 LICENSE 文件（开源协议），以及一个 index.js 文件。

现在，一个最基本的包就是准备好了，等待发布了。

2. 发布

既然包已经准备好了，那么就可以发布了。

2.0. 修正下载源

如果你曾经为了加速 NPM 下载速度而修改了它的下载源，那么请改回去，不然是无法发布的。

检查方式：

npm config get registry

NPM 的官方源是 https://registry.npmjs.org/，如果你看到控制台打印是这个，那么就没 问题了。而如果不是，那么请使用下面的命令修改回去：

npm config set registry https://registry.npmjs.org/

2.1. 创建并登录 npmjs.org 账户

如果你没有 npmjs.org 账户，那么先要创建一个，方法很简单：

npm adduser

根据提示创建即可。

记得验证邮箱，否则将无法发布包。

如果已经有 npmjs.org 账户了，请直接登录：

npm login

3. 真正的开始

上面的教程只是一个最简单的 DEMO，远远不能满足我们的发布需要，下面以一个需要编译的 TypeScript 包为例，看看如何发布和管理。

3.1. 合理的 package.json

先来看一个 package.json 的内容：

{
  "name": "full-sample",
  "version": "0.1.0",
  "description": "A sample to learn NPM.",
  "main": "./dist/index.js",
  "scripts": {
    "prepare": "npm run rebuild",
    "build": "tsc -p .",
    "rebuild": "npm run clean && npm run lint && npm run build",
    "test": "echo See directory sources/tests",
    "clean": "rm -rf dist",
    "lint": "tslint --project tslint.json"
  },
  "keywords": [
    "npm",
    "sample"
  ],
  "author": "NPM Learner <me@sample.com> (https://sample.com/)",
  "license": "Apache-2.0",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/learn-npm/full-sample.git"
  },
  "bugs": {
    "url": "https://github.com/learn-npm/full-sample/issues"
  },
  "homepage": "https://github.com/learn-npm/full-sample#readme",
  "types": "./dist/index.d.ts",
  "typings": "./dist/index.d.ts",
  "dependencies": {
    "sequelize": "^4.24.0"
  },
  "devDependencies": {
    "@types/node": "^8.0.51",
    "@types/sequelize": "^4.0.79",
    "typescript": "^2.6.1"
  },
  "engines": {
    "node": ">=8.0.0"
  }
}

假定项目的 TypeScript 源代码都在 sources 目录，编译结果都在 dist 目录。

上面与 DEMO 有什么区别呢？下面逐个字段解释：

• homepage

  指定项目的主页地址，如果没有一般可以使用项目的 GitHub 地址。

• bugs.url

  指定项目的 Bug 反馈地址，一般可以用项目的 GitHub Issue 地址。

• repository.url 和 repository.type

  指定项目的源码仓库地址，可以指定是 git/cvs/svn。

• main

  指定 Node.js 中 require("moduel-name") 导入的默认文件。

• keywords

  指定项目的关键词，合理设置有利于让他人发现你的项目。

• engines

  设置项目对引擎的版本要求，比如 node、electron、vscode 等。

• types 和 typings

  设置项目内置的 TypeScript 模块声明文件入口文件。

3.2. scripts 字段

scripts 字段作为单独一节解释，因为它是用于构建控制和发布控制的工具。

• scripts.build

  这个允许使用 npm run build 命令直接编译 TS 代码。

• scripts.lint

  这个允许使用 npm run lint 命令调用 TSLinter 对代码进行格式检查。

• scripts.clean

  这个允许使用 npm run clean 命令清理编译结果。

• scripts.rebuild

  这个允许使用 npm run rebuild 命令清理编译结果然后重新生成。

• scripts.prepare

  这个不是给我们用的，而是 NPM 提供的钩子，这个命令会在执行 npm publish 的时候 被调用。因此可以用这个钩子进行发布前构建。

3.3. Git 设置

Git 应当使用 .gitignore 文件忽略那些编译结果，以及 NPM 依赖的包文件：

/node_modules/
/dist/
*.log

3.4. NPM 包文件设置

NPM 打包发布的时候，会默认把当前目录下所有文件打包。但是 Git 仓库中，有些东西是不需要 发布到 NPM 的，因此我们需要使用一个文件 .npmignore 来忽略这些文件，常用配置如下：

/.git/
/.vscode/
/docs/
/node_modules/
.gitignore
.npmignore
tslint.json
tsconfig.json
*.log

这些文件都不是发布需要的内容，因此可以忽略。

3.5. 配置 tsconfig.json

前面说了，假定 TypeScript 的代码在 sources 目录下，编译的输出目录则为 dist。那么需要 在 tsconfig.json 里面通过 rootDir 和 outDir 选项指定。

其次，为了让其它 TypeScript 程序能正常使用你的包，你还应该设置 declaration 字段为 true，使之自动生成 *.d.ts 文件。此处我们假定模块的入口是 index.js ，因此你必须 实现一个 index.ts 文件，作为模块的入口。

另外，如果要实现 TypeScript 源码调试，则需要开启 sourceMap 选项，以生成源码映射 文件。

3.6. 使用 tslint.json

现在，就可以愉快地编写代码了吗？不不不，为了规范代码，我们还需要配置下 TSLinter。通过 下面的命令初始化一个 tslint.json 文件。

npm install tslint -g
tslint --init

TS Linter 的规则非常多，而且默认规则限制非常严格，可以适当根据提示解除一些限制。比如 作者就采用了如下配置，仅供参考：

{
    "defaultSeverity": "error",
    "extends": [
        "tslint:recommended"
    ],
    "jsRules": {
    },
    "rules": {
        "interface-name": false,
        "trailing-comma": false,
        "max-classes-per-file": false,
        "ordered-imports": false,
        "variable-name": false,
        "prefer-const": false,
        "member-ordering": false,
        "no-bitwise": false,
        "forin": false,
        "object-literal-sort-keys": false,
        "one-line": [false],
        "object-literal-key-quotes": [false],
        "no-string-literal": false,
        "no-angle-bracket-type-assertion": false,
        "only-arrow-functions": false,
        "no-namespace": false,
        "no-internal-module": false,
        "unified-signatures": false,
        "ban-types": false,
        "no-conditional-assignment": false,
        "radix": false
    },
    "rulesDirectory": []
}

如果想在 Visual Studio Code 里面实现 TS Linter 智能提示，则还需要安装 VSCode 的 TSLint 扩展。

现在，可以尽情地编写代码了。

4. 维护

4.1. 版本号维护

维护一个包，肯定是要进行包的版本升级的。如何进行呢？手动修改 package.json 的 version 字段是一个办法，但是显得有点 low。可以使用下面的命令：

npm version v0.1.0      # 版本号变成 0.1.0，即显式设置版本号。
npm version patch       # 版本号从 0.1.0 变成 0.1.1，即修订版本号加一。
npm version minor       # 版本号从 0.1.1 变成 0.2.0，即子版本号加一。
npm version major       # 版本号从 0.2.0 变成 1.0.0，即主版本号加一。

但是，除此之外，还有四条命令，用于创建“预发布版本”，也就是非稳定版本。

npm version v1.2.3

# 版本号从 1.2.3 变成 1.2.4-0，就是 1.2.4 版本的第一个预发布版本。
npm version prepatch

# 版本号从 1.2.4-0 变成 1.3.0-0，就是 1.3.0 版本的第一个预发布版本。
npm version preminor

# 版本号从 1.2.3 变成 2.0.0-0，就是 2.0.0 版本的第一个预发布版本。
npm version premajor

# 版本号从 2.0.0-0 变成 2.0.0-1，就是使预发布版本号加一。
npm version prerelease

注意： version 命令默认会给你的 git 仓库自动 commit 一把，并打一个 tag。如果不想它动你的 git 仓库，你应该使用 --no-git-tag-version 参数，例如：

npm --no-git-tag-version version patch

如果你想一劳永逸，那么可以使用如下 NPM 设置彻底禁止它：

npm config set git-tag-version false  # 不要自动打 tag
npm config set commit-hooks false     # 不要自动 commit

4.2. 使用标签

以 TypeScript 为例，通过 npm info typescript 可以看到 dist-tags 字段有着五个 值，分别是 latest, beta, rc, next, insiders，这些都是 dist-tag，可以 称之为标签——你可以把它理解为 git 里面的分支。

有什么用呢？其实，我们平时用 npm install xxxxxx 的时候，是使用了一个潜在的选项 tag = latest，可以通过 npm config list -l | grep tag 看到。

因此实际上是执行了 npm install xxxxxx@latest。也就是安装了 latest 这个标签 对应的最新版本。

不同的标签可以有不同的版本，这就方便我们发表非稳定版本到 npm 上，与稳定版本分开。

默认是发布到 latest 标签下的。

例如 npm publish --tag dev 就可以发布一个版本到 dev 标签下。

4.3. 使用前缀

如果你使用过 AngularJS 或者 TypeScript，那么肯定知道有一些包的名字是这样的：

• @types/node
• @types/jquery
• @angular/core

这里面的 @types/ 和 @angular/ 叫做包前缀（scope）。

作者起初以为使用包前缀也是收费的，后来仔细阅读了文档才发现公开的包可以免费使用 包前缀。

那我们怎么使用呢？很简单，首先在 package.json 里面把 name 字段加上一个前缀。

前缀必须是你 NPM 账户的用户名，比如你注册了一个用户名为 abc 的账户，则你只能使用 @abc/ 为你的包前缀。

举个例子，将你的包名设置为 @abc/test。

如果你要初始化一个带包前缀的包，则可以使用下面的命令。

npm init --scope=abc # 当然你还可以加上个 `-y` 快速创建。

或者你想每次都使用 @abc/ 包前缀？加个设置即可：

# 这样每次初始化新的 package.json，都将自动应用 @abc/ 包前缀。
npm config set scope abc

现在，可以发布你的包到 npmjs.org 了。哦不，别忘了一点：

官方文档表示：所有带前缀的包，在发布的时候，默认都是发布为私有包。

这意味着你不能就这么发布，因为你（可能）不是付费用户，不能发布私有的包。那怎么办呢？别 担心，npm publish 命令还有一个参数 --access ，通过这个参数可以指定发布的是公共包 还是私有包。因此，只要用下面的命令就可以发布一个公共的，带包前缀的包了：

npm publish --access=public

（完）

转载于:https://my.oschina.net/fenying/blog/1607571