---
url: /zh/artifact/npm.md
description: |
  介绍如何配置和使用 CNB npm 制品库， 包括本地开发凭证配置、包的发布和安装， 以及在流水线中集成 npm 制品库的方法。
---
## 前置准备

1. [创建制品库](./intro.md#创建制品库)

2. [获取制品库的地址](./intro.md#获取制品库的地址)

3. [创建令牌](./intro.md#创建访问令牌)

## 本地开发

### 配置凭证

#### npm

支持以下三种方式

##### .npmrc 中配置凭据

粘贴以下内容到项目的 package.json 同一级目录下的 .npmrc

替换 `<YOUR_TOKEN>` 为你的令牌，`<REPO_URL>` 为制品库地址，`<REPO_URL_SUFFIX>` 为制品库地址去掉协议前缀

```ini
# 示例
# registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=<YOUR_TOKEN>

registry=<REPO_URL>
always-auth=true
//<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>
```

##### 命令行交互

1. 设置制品仓库，替换 `<REPO_URL>` 为制品库地址

```bash
# 示例
# npm config set registry https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/

npm config set registry <REPO_URL>
```

2. 使用交互式登录命令，您的 username 为 `cnb`，password 为访问令牌

```bash
npm login
```

##### 命令行设置

替换 `<YOUR_TOKEN>` 为你的令牌，`<REPO_URL>` 为制品库地址，`<REPO_URL_SUFFIX>` 为制品库地址去掉协议前缀

```bash
# 示例
# npm config set registry https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# npm config set //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=<YOUR_TOKEN>

npm config set registry <REPO_URL>
npm config set //<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>
```

#### Yarn

##### Yarn 1.x 配置方式

如果你的 Yarn 版本是 1.x，可以使用如下方式配置凭证：

###### .npmrc 中配置凭据

粘贴以下内容到项目的 `package.json` 同级目录下的 `.npmrc` 文件中。

替换 `<YOUR_TOKEN>` 为你的令牌，`<REPO_URL>` 为制品库地址，`<REPO_URL_SUFFIX>` 为制品库地址去掉协议前缀。

```ini
# 示例
# registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=<YOUR_TOKEN>

registry=<REPO_URL>
always-auth=true
//<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>
```

###### 命令行交互

此命令仅适用于本地推送制品，替换 `<REPO_URL>` 为制品库地址

```bash
# 示例
# yarn config set registry https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/

yarn config set registry  <REPO_URL>
yarn publish
# .....
question npm password: 这里输入你的令牌
```

##### Yarn > 1.x 配置方式

如果您使用的 Yarn 版本 > 1.x，有两种方案，但是最后都是修改与 package.json 同级的 .yarnrc.yml

###### 修改.yarnrc.yml

在 .yarnrc.yml 中配置凭据，替换 `<REPO_URL>` 为制品库地址， `<YOUR_TOKEN>` 为你的令牌

```yaml
npmPublishRegistry: "<REPO_URL>"
npmRegistryServer: "<REPO_URL>"

npmRegistries:
  "<REPO_URL>":
    npmAlwaysAuth: true
    npmAuthToken: <YOUR_TOKEN>
```

###### 命令行配置

替换 `<REPO_URL>` 为制品库地址， `<YOUR_TOKEN>` 为你的令牌

```bash
yarn config set npmPublishRegistry <REPO_URL> # 推送包的地址
yarn config set npmRegistryServer <REPO_URL> # 拉取包的地址
yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' <YOUR_TOKEN>
```

这样操作后会产生这样的 .yarnrc.yml

```yaml
npmPublishRegistry: "<REPO_URL>"
npmRegistryServer: "<REPO_URL>"
npmRegistries:
  "<REPO_URL>":
    npmAuthToken: <YOUR_TOKEN>
```

#### pnpm

参考 npm，仅需将命令中的 npm 替换为 pnpm

### 拉取制品

替换 `<PACKAGE_NAME>`，`<VERSION>`， `<REPO_URL>`

```bash
# 示例
# npm install express@5.1.0 --registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/

# npm
npm install <PACKAGE_NAME>@<VERSION> --registry=<REPO_URL>

# yarn
yarn add <PACKAGE_NAME>@<VERSION>

# pnpm
pnpm install <PACKAGE_NAME>@<VERSION> --registry=<REPO_URL>
```

### 推送制品

1. 初始化 package.json，注意替换 `<PACKAGE_NAME>` 和 `<VERSION>`

```json
{
  "name": "<PACKAGE_NAME>",
  "version": "<VERSION>",
  "description": "",
  "main": "index.js",
  "author": "",
  "license": "MIT"
}
```

2. 执行如下命令发布包，替换 `<REPO_URL>` 为制品库地址

```bash
# <REPO_URL>示例
# https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/

# npm
npm publish --registry=<REPO_URL>

# yarn 版本 > 1.x
yarn npm publish

# yarn 版本 为 1.x
yarn publish --registry=<REPO_URL>

# pnpm
pnpm publish --registry=<REPO_URL>
```

## 云原生构建

### 配置凭证

云原生构建使用令牌有三种方式，参考 [云原生构建，云原生开发中使用令牌](./intro.md#在云原生构建，云原生开发中使用令牌)，
以下是具体客户端的使用方式：

#### npm

##### .npmrc 中配置凭据

粘贴以下内容到项目的 package.json 同一级目录下的 .npmrc

替换 `<REPO_URL>` 为制品库地址，`<REPO_URL_SUFFIX>` 为制品库地址去掉协议前缀

```ini
# 示例
# registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=${CNB_TOKEN}

registry=<REPO_URL>
always-auth=true

# 第一种方式 使用内置环境变量 CNB_TOKEN
//<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}

# 第二种方式 直接使用，替换 <YOUR_TOKEN> 为你的令牌即可
# //<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>

# 第三种方式，密钥仓库，替换 <ENV_NAME> 为您密钥仓库的变量
# //<REPO_URL_SUFFIX>:_authToken=${<ENV_NAME>}
```

##### npm config 设置

替换 `<REPO_URL>` 为制品库地址，`<REPO_URL_SUFFIX>` 为制品库地址去掉协议前缀

```bash
# 示例
# npm config set registry https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# npm config set //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=${CNB_TOKEN}

npm config set registry <REPO_URL>

# 第一种方式 使用内置环境变量 CNB_TOKEN
npm config set //<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}

# 第二种方式 直接使用，替换 <YOUR_TOKEN> 为你的令牌即可
# npm config set //<REPO_URL>:_authToken=<YOUR_TOKEN>

# 第三种方式，密钥仓库，替换 <ENV_NAME> 为您密钥仓库的变量
# npm config set //<REPO_URL>:_authToken=${<ENV_NAME>}
```

#### Yarn

##### Yarn 1.x 配置方式

如果你的 Yarn 版本是 1.x，可以使用如下方式配置凭证。

粘贴以下内容到项目的 `package.json` 同级目录下的 `.npmrc` 文件中，
替换 `<REPO_URL>` 为制品库地址，`<REPO_URL_SUFFIX>` 为制品库地址去掉协议前缀。

```ini
# 示例
# registry=https://npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnbprod.alpha.qq.com/cnb/npm-repo/-/packages/:_authToken=${CNB_TOKEN}

registry=<REPO_URL>
always-auth=true

# 第一种方式 使用内置环境变量 CNB_TOKEN
//<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}

# 第二种方式 直接使用，替换 <YOUR_TOKEN> 为你的令牌即可
# //<REPO_URL_SUFFIX>:_authToken=<YOUR_TOKEN>

# 第三种方式，密钥仓库，替换 <ENV_NAME> 为您密钥仓库的变量
# //<REPO_URL_SUFFIX>:_authToken=${<ENV_NAME>}
```

##### Yarn > 1.x 配置方式

如果您使用的 Yarn 版本 > 1.x，有两种方案，但是最后都是修改与 package.json 同级的 .yarnrc.yml

###### 修改.yarnrc.yml

```yaml
npmPublishRegistry: "<REPO_URL>" # 推送包的地址
npmRegistryServer: "<REPO_URL>" # 拉取包的地址

npmRegistries:  # 配置每个制品库的凭证
  "<REPO_URL>":
    npmAlwaysAuth: true
    # 第一种方式 使用内置环境变量 CNB_TOKEN
    npmAuthToken: ${CNB_TOKEN}
    # 第二种方式 直接使用，替换 <YOUR_TOKEN> 为你的令牌即可
    # npmAuthToken: <YOUR_TOKEN>
    # 第三种方式，密钥仓库，替换 <ENV_NAME> 为您密钥仓库的变量
    # npmAuthToken: ${<ENV_NAME>}
```

###### 命令行设置

```bash
yarn config set npmPublishRegistry <REPO_URL> # 推送包的地址
yarn config set npmRegistryServer <REPO_URL> # 拉取包的地址

# 第一种方式 使用内置环境变量 CNB_TOKEN
yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' ${CNB_TOKEN}

# 第二种方式 直接使用，替换 <YOUR_TOKEN> 为你的令牌即可
# yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' <YOUR_TOKEN>

# 第三种方式，密钥仓库，替换 <ENV_NAME> 为您密钥仓库的变量
# yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' ${<ENV_NAME>}
```

#### pnpm

参考 npm，仅需将命令中的 npm 替换为 pnpm

### 拉取制品

#### npm

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: npm install
          script:
            - npm config set registry <REPO_URL>
            - npm config set //<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}
            - npm install --registry=<REPO_URL>
```

> 如果已通过 `.npmrc` 配置凭据，可直接使用 `npm install --registry=<REPO_URL>` 代替上述三个命令。

#### Yarn

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: yarn install
          script:
            - npm install -g corepack
            - corepack enable
            - corepack prepare yarn@1.22.22 --activate

            # 如果yarn版本 > 1.x，同时使用命令行配置，需带下面两行
            # - yarn config set npmRegistryServer <REPO_URL>
            # - yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' ${CNB_TOKEN}

            - yarn install
```

#### pnpm

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: pnpm install
          script:
            - pnpm config set registry <REPO_URL>
            - pnpm config set //<REPO_URL_SUFFIX>/:_authToken=${CNB_TOKEN}
            - pnpm install
```

### 推送制品

核心配置：在 `tag_push` 事件中更新版本号并发布。以下以 npm（推荐 `tencentcom/npm` 插件）为例：

```yaml title=".cnb.yml"
$:
  tag_push:
    - docker:
        image: node:22
      stages:
        - name: update version
          script: npm version $CNB_BRANCH --no-git-tag-version
        - name: npm publish
          image: tencentcom/npm
          settings:
            username: $CNB_TOKEN_USER_NAME
            token: $CNB_TOKEN
            email: $CNB_COMMITTER_EMAIL
            registry: <REPO_URL>
            folder: ./
            fail_on_version_conflict: true
```

其他包管理器的发布方式（替换上述 npm 对应的 stages 即可）：

* **Yarn 1.x**：安装 `yarn@1.x`，用 `yarn version --new-version=$CNB_BRANCH` 更新版本，`yarn publish` 发布。
* **Yarn > 1.x**：安装 `yarn@4.x`，用 `yarn version $CNB_BRANCH` 更新版本，`yarn npm publish` 发布。
* **pnpm**：安装 `pnpm`，用 `pnpm version $CNB_BRANCH --no-git-tag-version` 更新版本，
  先执行 `pnpm config set` 配置凭据，再 `pnpm publish --no-git-checks` 发布。

## 云原生开发

### 配置凭证

与 [云原生构建 配置凭证](./npm.md#配置凭证-1) 相同

### 配置开发镜像

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        image: node:22
```

可执行如下命令选择包管理器，替换 `<NAME>` 和 `<VERSION>` 为你的包管理器名称和版本。

```bash
npm install -g corepack
corepack enable
# 示例 corepack prepare yarn@1.22.22 --activate
corepack prepare <NAME>@<VERSION> --activate
```

### 拉取制品

与 [本地开发 拉取制品](./npm.md#拉取制品) 相同

### 推送制品

与 [本地开发 推送制品](./npm.md#推送制品) 相同

## 更多用法

更多 npm 用法，请查阅 [npm 官方文档](https://docs.npmjs.com/)。