# 配置渠道与灰度发布

在控制台创建渠道，把渠道写进安装包，再按渠道发布更新。

## 先选一种用法 {#before}

只发一个安装包时，不用配置，渠道就是 `default`。要分别给华为、小米或内部测试人员发更新，再按本页设置。

下面以 Android 的 `huawei` 渠道为例：先在控制台创建渠道，再把同一个名称写进 App，重新打包、上传，最后发布更新。

## 渠道有什么用 {#what-is-a-channel}

同一应用可以给不同渠道发不同更新。例如，华为用户先更新 10%，小米用户更新 100%。这里的百分比指符合条件的设备比例。

| 你填写的内容 | 示例 | 填在哪里 |
| --- | --- | --- |
| 渠道名称 | 华为应用市场 | 控制台，方便自己辨认 |
| 渠道 code | `huawei` | 控制台和 App 配置，两边必须一致 |
| 原生版本 | `1.0.0` | Android 的 `versionName` / iOS 的版本号 |

## 1. 在控制台创建渠道 {#manage}

1. 登录控制台，打开**应用**，进入要发布的应用。
2. 切到**渠道目录**，点击**创建渠道**。
3. **渠道 code** 填 `huawei`，**渠道名称**填“华为应用市场”。
4. 保持**启用热更新**开启，**忽略时间戳/内容指纹检查**关闭。原生包下载地址可以先留空。
5. 保存，确认列表出现 `huawei`。

code 只能使用 1–64 个小写字母、数字、点、下划线或短横线，创建后不能修改。默认渠道 `default` 不需要再创建。

也可以在已选好应用的工程根目录执行：

```bash
pakta createChannel --name huawei --code huawei
pakta channels --platform android
```

## 2. 把渠道写进 App {#identity}

选自己的平台操作。**渠道在安装包里，不能通过 `new Pakta()` 或上传命令修改。改完必须重新构建并安装 App。**

### Android {#android}

打开 `android/app/src/main/AndroidManifest.xml`，在已有的 `<application>` 内添加下面一行，保留原有属性和 `<activity>`：

```xml title="android/app/src/main/AndroidManifest.xml · application 内"
<meta-data android:name="channel" android:value="huawei" />
```

然后在 `android` 目录构建：

```powershell title="Windows"
.\gradlew.bat assembleRelease
```

```bash title="macOS / Linux"
./gradlew assembleRelease
```

没有配置 product flavor 的工程通常生成 `android/app/build/outputs/apk/release/app-release.apk`。安装这份 APK，并保留它供下一步上传。

如果已有多个 flavor，可把值改为 `${PAKTA_CHANNEL}`，在 `android/app/build.gradle` 的现有 flavor 内分别配置 `manifestPlaceholders`，例如 `manifestPlaceholders = [PAKTA_CHANNEL: "huawei"]`。每个 flavor 都要提供值，再运行对应的 Release 构建任务。

### iOS {#ios}

打开 **App target 使用的** `ios/你的工程名/Info.plist`，在根 `<dict>` 内加入：

```xml title="Info.plist · dict 内"
<key>channel</key>
<string>appstore</string>
```

如果工程由 Xcode 自动生成 Info.plist，在 App target 的 **Info → Custom iOS Target Properties** 添加 String 类型的 `channel`，值填 `appstore`。不要修改 Pods 的 Info.plist。

控制台创建同名 code `appstore`。重新 Archive，导出并保留 IPA，安装对应构建。

### HarmonyOS {#harmonyos}

完成[HarmonyOS 接入](/docs/getting-started#harmonyos)后，打开或创建 `harmony/entry/src/main/resources/rawfile/meta.json`，增加 `channel` 字段：

```json title="harmony/entry/src/main/resources/rawfile/meta.json"
{
  "channel": "huawei"
}
```

已有其他字段时保留它们。SDK 的 Hvigor 插件在构建时保留渠道，并写入版本和构建时间。用 DevEco Studio 重新签名、构建 `.app`，安装并保留这份文件。

### Expo {#expo}

手工维护 `android` / `ios` 目录时，按上面原生配置操作。使用 Expo `prebuild` 或 EAS 时，在 `expo.plugins` 加入：

```json title="app.json · expo.plugins"
{
  "expo": {
    "plugins": [
      ["rn-update", { "channel": "huawei" }]
    ]
  }
}
```

`channel` 会同时写入 Android Manifest 和 iOS `Info.plist`。不同平台使用不同渠道时，使用不同构建配置。`default` 不需要插件。详见[Expo 接入](/docs/expo#channel)。

## 3. 检查并上传安装包 {#verify}

回到含 `package.json` 的应用根目录：

```bash
pakta selectApp --platform android
pakta parseApk ./android/app/build/outputs/apk/release/app-release.apk
pakta uploadApk ./android/app/build/outputs/apk/release/app-release.apk --channel huawei
```

先看解析结果中的渠道是否为 `huawei`、版本号是否正确，再上传。`--channel huawei` 只检查包内渠道；报不一致时，回到配置文件修正并重新打包。

| 平台 | 检查命令 | 上传命令 |
| --- | --- | --- |
| Android APK | `parseApk 路径` | `uploadApk 路径 --channel huawei` |
| Android AAB | `parseAab 路径` | `uploadAab 路径 --channel huawei` |
| iOS | `parseIpa 路径` | `uploadIpa 路径 --channel appstore` |
| HarmonyOS | `parseApp 路径` | `uploadApp 路径 --channel huawei` |

回到控制台，打开**原生包体**并刷新，应能看到该渠道和版本。没有这条记录时，发布窗口不会出现对应目标。

## 4. 向渠道发布更新 {#targets}

先按[首次发布](/docs/publish#bundle)生成 `.ppk`，再执行：

```bash
pakta publish .pakta/output/android.ppk --platform android --name fix-001 --channel huawei --packageVersion 1.0.0 --rollout 10 --no-interactive
```

把 `1.0.0` 换成刚上传安装包的版本。测试应用可以用 `100`，生产应用先用小比例验证。网页操作见[控制台发布步骤](/docs/console#publish)。

需要一次发布到多个渠道时，在工程根目录创建：

```json title="targets.json"
[
  { "channel": "huawei", "packageVersion": "1.0.0", "rollout": 10 },
  { "channel": "xiaomi", "packageVersion": "1.0.0", "rollout": 100 }
]
```

```bash
pakta publish .pakta/output/android.ppk --platform android --name fix-001 --targets targets.json --no-interactive
```

这两个渠道都必须已有对应原生包。iOS、Android、HarmonyOS 分别打包和发布，不能共用一份 `.ppk`。

## 调整比例、停止与恢复 {#lifecycle}

在**热更新包**中找到版本，点目标上的渠道/版本标签，调整比例；或点**发布**编辑多个目标。每次都先检查预览，再确认提交。

- 停止某个版本继续发布：对该目标选择**取消发布**。
- 停止整个渠道更新：**渠道目录 → 配置 → 关闭启用热更新 → 保存设置**。
- 恢复旧版本：找到稳定的历史包，对相同渠道和原生版本选择**回滚为全量**。

停止更新、缩小比例都不会撤销设备已经安装的更新。恢复旧版本也要等设备检查、下载并按 App 的设置生效。详细步骤见[停止与回滚](/docs/console#rollback)。

## 内部测试怎么安排 {#practices}

创建 `internal` 渠道，按本页把渠道写进测试安装包。每次先向 `internal` 发布并验证，再向生产渠道发布。测试人员要安装 `internal` 包；在控制台改名称不会改变手机所属渠道。