---
url: /zh/artifact/composer.md
description: |
  介绍如何配置和使用 CNB Composer 制品库， 包括推送凭据配置和通过 REST API 上传 PHP 包的方法。
---
## 推送凭据配置

通过 CNB REST API 上传制品文件到 Composer 制品库。`CNB_TOKEN` 的获取方式请参考 [创建访问令牌](./intro.md#创建访问令牌)。

### 方式一：配置 .netrc 自动加载凭据

```shell
printf "\nmachine composer.cnbprod.alpha.qq.com\nlogin cnb\npassword %s\n" "<CNB_TOKEN>" >> ~/.netrc
```

### 方式二：在 curl 命令中直接指定凭据

```shell
curl -ucnb:<CNB_TOKEN> https://composer.cnbprod.alpha.qq.com/xxx... -T <PATH_TO_FILE>
```

## 拉取凭据配置

1. 添加制品库地址到全局 config.json（通常位于 `~/.composer/config.json`）。
   `CNB_COMPOSER_URL` 的获取方式请参考 [获取制品库地址](./intro.md#获取制品库的地址)。

```shell
composer config repos.packgist false -g
composer config repos.cnb composer <CNB_COMPOSER_URL> -g
```

2. 添加凭据到全局 auth.json（通常位于 ~/.composer/auth.json）：

```shell
composer config http-basic.composer.cnbprod.alpha.qq.com cnb <CNB_TOKEN> -g
```

## 推送制品

### 本地命令行推送

1. 将以下内容粘贴到 composer.json，避免打包认证信息和依赖：

```json
{
    "archive": {
        "exclude": ["auth.json", "composer.lock", "vendor"]
    }
}
```

2. 进入包目录，打包 Composer 制品：

```shell
composer archive -f zip --file package
```

3. 发布到 CNB

**注意：**

1. `CNB_COMPOSER_URL` 的获取方式请参考 [获取制品库地址](./intro.md#获取制品库的地址)
2. `<vendor>/<package>/<version>` 需替换为当前包的实际值，例如 `monolog/monolog/3.8.1`

```shell
curl --netrc "<CNB_COMPOSER_URL>upload/<vendor>/<package>/<version>" -T package.zip
```

### 云原生构建中推送

将以下内容粘贴到 `.cnb.yml`，提交后推送 Tag 触发构建（Tag 值将作为制品版本号）。
`CNB_COMPOSER_URL` 需替换为实际值，`<vendor>/<package>` 替换为当前包的实际值
（如 `monolog/monolog`）。

```yaml title=".cnb.yml"
$:
  tag_push:
    - docker:
        image: docker.cnb.cool/examples/language/php-8.4
      stages:
        - name: setup netrc
          # 配置推送凭据（CNB 自动注入 CNB_TOKEN 环境变量）
          script: printf "machine composer.cnbprod.alpha.qq.com\nlogin cnb\npassword %s\n" "${CNB_TOKEN}" > ~/.netrc
        - name: archive
          # 打包 Composer 制品为 package.zip
          script: composer archive -f zip --file package
        - name: upload
          # ${CNB_BRANCH} 在 tag_push 事件下即 Tag 名，作为制品版本号
          script: curl --netrc -T package.zip "<CNB_COMPOSER_URL>upload/<vendor>/<package>/${CNB_BRANCH}"
```

> 请确保 `composer.json` 中已配置 `archive.exclude` 避免打包认证信息
> （参考上方「本地命令行推送」中的 composer.json 示例）。请使用 [语义版本号](https://semver.org/lang/zh-CN/)。

### 云原生开发中推送

将以下内容粘贴到 `.cnb.yml`，提交到代码仓库后，点击代码仓库页面右上角
**「云原生开发」** 按钮进入开发环境，然后在终端中配置凭据并推送：

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        image: docker.cnb.cool/examples/language/php-8.4
      services:
        - vscode
        - docker
```

```shell
# 配置凭据
printf "machine composer.cnbprod.alpha.qq.com\nlogin cnb\npassword %s\n" "${CNB_TOKEN}" > ~/.netrc
# 打包并上传（<vendor>/<package>/<version> 替换为实际值，如 monolog/monolog/3.8.1）
composer archive -f zip --file package
curl --netrc -T package.zip "<CNB_COMPOSER_URL>upload/<vendor>/<package>/<version>"
```

> 请确保 `composer.json` 中已配置 `archive.exclude`（参考上方「本地命令行推送」中的示例）。

## 使用制品

### 拉取制品

按照上文 [拉取凭据配置](#la-qu-ping-ju-pei-zhi) 配置凭证后，使用以下命令拉取制品：

```shell
composer require monolog/monolog
```

### 删除制品

Composer 没有提供删除命令，请参考 [删除制品](./intro.md#删除制品)。

## FAQ

### Q1: 上传制品报错没有权限

**示例：**

```shell
curl --netrc <CNB_COMPOSER_URL>upload/monolog/monolog/3.8.0 -T monolog.zip
{"errcode":16,"errmsg":"not authorized"}
```

**解决方案：**

参考 [创建令牌](./intro.md#创建访问令牌) 和 [推送凭据配置](#tui-song-ping-ju-pei-zhi) 正确配置凭据。

### Q2: 上传制品报错版本号格式不对

**示例：**

```shell
curl --netrc <CNB_COMPOSER_URL>upload/monolog/monolog/xxx3.8.0 -T monolog.zip
{"errcode":3,"errmsg":"validate [Version:xxx3.8.0] failed"}
```

**解决方案：**

请使用 [语义版本号](https://semver.org/lang/zh-CN/)。

### 关于 Composer 1.x

官方源已于 2025 年 8 月 1 日停止对 Composer 1.x 的支持。CNB Composer 制品库推荐使用 Composer 2.x 及以上版本。

如果仍在使用 Composer 1.x，可通过 `composer self-update` 命令更新为 2.x 最新稳定版本。