---
url: /zh/artifact/npm.md
---
## 前置准备

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

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

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

## 本地开发

### 配置凭证

::: tabs

@tab npm
有以下三种方式

#### .npmrc 中配置凭据

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

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

```ini
# 示例
# registry=https://npm.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# npm config set //npm.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/:_authToken=<YOUR_TOKEN>

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

@tab Yarn

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

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

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

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

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

```ini
# 示例
# registry=https://npm.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/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>
```

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

### 拉取制品

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

```bash
# 示例 
# npm install express@5.1.0 --registry=https://npm.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/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#在云原生构建，云原生开发中使用令牌)，以下是具体客户端的使用方式

::: tabs
@tab npm

#### .npmrc 中配置凭据

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

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

```ini
# 示例
# registry=https://npm.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.share.ralphlauren.cn/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.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# npm config set //npm.cnb.share.ralphlauren.cn/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>}
```

@tab Yarn

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

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

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

```ini
# 示例
# registry=https://npm.cnb.share.ralphlauren.cn/cnb/npm-repo/-/packages/
# always-auth=true
# //npm.cnb.share.ralphlauren.cn/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>}
```

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

### 拉取制品

::: tabs
@tab npm
使用.npmrc配置方式可参考如下配置，替换 `<REPO_URL>` 为制品库地址

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: npm install
          script:
            - npm install --registry=<REPO_URL>
```

使用npm config设置方式可参考如下配置，替换 `<REPO_URL>` 为制品库地址，`<REPO_URL_SUFFIX>` 为制品库地址去掉协议前缀

```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>
```

@tab 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
```

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

### 推送制品

::: tabs
@tab npm
推荐使用 tencentcom/npm 镜像，将如下内容粘贴到 .cnb.yml

```yaml title=".cnb.yml"
$:
  # tag push 时触发
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: update version
        # $CNB_BRANCH 为流水线自带环境变量，为当前提交的tag
        # 修改 package.json 中的version为当前tag，但不会提交代码
        script: npm version $CNB_BRANCH --no-git-tag-version
      - name: npm publish
        image: tencentcom/npm
        settings:
          # CNB_TOKEN_USER_NAME, CNB_TOKEN，CNB_COMMITTER_EMAIL 为流水线自带环境变量
          username: $CNB_TOKEN_USER_NAME
          token: $CNB_TOKEN
          email: $CNB_COMMITTER_EMAIL
          registry: <REPO_URL>
          folder: ./
          fail_on_version_conflict: true
```

@tab Yarn
如果您使用的Yarn版本为1.x

```yaml title=".cnb.yml"
$:
  # tag push 时触发
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: install yarn
        script: 
          - npm install -g corepack
          - corepack prepare yarn@1.22.22 --activate
      - name: update version
        # $CNB_BRANCH 为流水线自带环境变量，为当前提交的tag
        script: yarn version --new-version=$CNB_BRANCH 
      - name: yarn publish
        script: yarn publish     
```

如果您使用Yarn版本 > 1.x

```yaml title=".cnb.yml"
$:
  # tag push 时触发
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: install yarn
        script: 
          # 需要额外拉取打tag的分支信息
          - git pull origin main 
          - npm install -g corepack
          - corepack prepare yarn@4.9.2 --activate
      - name: update version
        # $CNB_BRANCH 为流水线自带环境变量，为当前提交的tag
        script: yarn version $CNB_BRANCH 
      # 使用命令行配置凭证，需带上下面的stage
      # - name: yarn auth
      #   script:
      #     - yarn config set npmPublishRegistry <REPO_URL>
      #     - yarn config set 'npmRegistries[<REPO_URL>].npmAuthToken' ${CNB_TOKEN}
      - name: yarn publish
        script: yarn npm publish
```

@tab pnpm
如果您使用命令行配置密钥，则将如下内容粘贴到 .cnb.yml，替换 `<REPO_URL>` 为制品库地址，`<REPO_URL_SUFFIX>` 为制品库地址去掉协议前缀

```yaml title=".cnb.yml"
$:
  # tag push 时触发
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: install pnpm
        script: 
          - npm install --global corepack@latest
          - corepack enable pnpm
      - name: update version
        # $CNB_BRANCH 为流水线自带环境变量，为当前提交的tag
        # 修改 package.json 中的version为当前tag，但不会提交代码
        script: pnpm version $CNB_BRANCH --no-git-tag-version
      - name: login registry
        script: 
          - pnpm config set registry <REPO_URL>
          - pnpm config set //<REPO_URL_SUFFIX>:_authToken=${CNB_TOKEN}
      - name: pnpm publish
        script: pnpm publish --no-git-checks
```

如果您使用 .npmrc 配置密钥，则将如下内容粘贴到 .cnb.yml

```yaml title=".cnb.yml"
$:
  # tag push 时触发
  tag_push:
    - docker:
        image: node:22
      stages:
      - name: install pnpm
        script: 
          - npm install --global corepack@latest
          - corepack enable pnpm
      - name: update version
        # $CNB_BRANCH 为流水线自带环境变量，为当前提交的tag
        # 修改 package.json 中的version为当前tag，但不会提交代码
        script: pnpm version $CNB_BRANCH --no-git-tag-version 
      - name: pnpm publish
        script: 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 官方文档