摘要：发布一款鸿蒙应用，过去要在开发者中心切换七八个页面：查 App ID、申请证书、创建 Profile、上传软件包、提交审核、配置测试——每一步都要定位菜单、填表单、等响应。本文用 hmos-connect-api-cli-skill 把这条链路重构为一条可复用的命令链：auth status 一次判定凭证、project list 查项目、csr-generate → cert-create → profile-create 生成发布签名材料、assembleApp 出 .app、upload file 提审。附改造前后对比、6 个静默失败点、一份上架前检查清单和 5 条产品建议。

目录

• 背景与前置
• 改造前后：从页面跳转到命令链
• 核心过程
• 踩坑与排错
• 结论与适用边界
• 参考资料
• 附：产品体验建议

背景与前置

版本环境

项	本文环境
系统	Windows 11
Node.js	v24 LTS（最低 18.x）
DevEco Studio	26（提供 SDK / hvigorw / hdc / hap-sign-tool）
目标	HarmonyOS 应用上架 + 邀请测试分发

读者画像：已能本地出包、准备或正在上架鸿蒙应用的个人/独立开发者。本文不解释 AGC 概念，只讲链路与坑。

前置门禁（两个变量决定后面能不能跑通）：.env 里的开发者中心凭证，以及 DEVECO_HOME（DevEco 安装目录）。凡涉及签名、构建、hdc 的步骤都从后者推 SDK 与工具路径。

# .env 只需这几个键（.env 本身不入库、不提交）
AGC_AUTH_MODE=service_account
AGC_SA_CREDENTIALS=<控制台下载的 *_private.json 路径>
DEVECO_HOME=<DevEco Studio 安装目录>

本机实际配置（密钥路径已打码）：

实测本机为 service_account 模式（凭据文件路径已脱敏），DEVECO_HOME 指向 DevEco 安装目录。
也可以用 API 客户端模式：AGC_CLIENT_ID + AGC_CLIENT_SECRET（控制台「开发者管理 → ID、证书和 Profile → 凭证」获取）。

0. 安装 Skill：Matrix 市场一行装好

技能通过 Matrix 市场分发，当前版本 1.0.2（Apache-2.0）：

项目	信息
技能名称	hmos-connect-api-cli-skill
当前版本	1.0.2
许可证	Apache-2.0
发布来源	Matrix 市场（matrix.openharmony.cn）
源码仓库	gitcode.com/HarmonyOS_Skills/harmonyos-agent-skills
热度（抓取时）	下载 1010 · 浏览 1625 · 2026-09-21 更新
运行依赖	仅需 Node.js，无需 npm 安装

三种安装方式，任选其一：

# 方式一：Matrix CLI
matrix skill install hmos-connect-api-cli-skill

# 方式二：npx
npx skills add https://matrix.openharmony.cn/api/registry/skills/hmos-connect-api-cli-skill

方式三：把下面这句提示词发给你的 Agent，让它按官方托管源文档自动安装：

请访问地址 https://matrix.openharmony.cn/api/registry/skill/matrix_skill_guide.md
获取 Matrix 市场托管源安装指导文档，根据文档指引安装 hmos-connect-api-cli-skill 技能。

装完后技能目录自带 scripts/connect-api-cli.js，后续所有命令都通过它执行（不要 npm install -g）。

改造前后：从页面跳转到命令链

环节	改造前（控制台）	改造后（CLI Skill）
查 App ID	我的应用 → 选择应用 → 复制 App ID	publish app-id -p <包名>
证书	证书管理 → 新建 → 上传 CSR → 下载 .cer	csr-generate → cert-create
Profile	Profile 管理 → 新建 → 选证书/设备 → 下载 .p7b	profile-create
设备调试	设备管理 → 添加 UDID	device-add
上传包	版本管理 → 上传软件包	upload file
提交审核	版本管理 → 提交审核 → 填物料	publish 提交接口
测试分发	邀请测试 → 建分组 → 加成员 → 发邀请码	test 系列命令

改造后的收益不是「少点几次鼠标」，而是流程可脚本化、可复查、可交接：每一步都有确定的输入与输出，出错能定位到具体命令与字段。

核心过程

1. 接入：一条命令判定「凭证在不在、要不要登录」

hmos-connect-api-cli-skill 自带 CLI 脚本，Node 直接跑，不装全局包：

node scripts/connect-api-cli.js auth status

这一条同时回答三件事：凭证是否读得到（只在当前工作目录找 .env，换目录即失效）、token 是否已缓存及剩余时间、登录模式（OAuth 模式需人工在浏览器点授权）。输出形如：

# 输出示意（字段已脱敏）
Auth mode: api_client
Token cached: yes
Expires in: 47 min

看到 Token cached: yes 即可进下一步，无需重复 auth login。

2. 查应用与 ID：全部从上游提取，不手抄

上架链路里最容易错的是 ID 串台——把 A 应用的 appId 用到 B 应用的 Profile 上，报错会指向完全无关的位置。CLI 的做法是每步都从上游输出取：

node scripts/connect-api-cli.js project list                    # 项目 → projectId
node scripts/connect-api-cli.js publish app-id -p <你的包名>     # 包名 → appId
node scripts/connect-api-cli.js publish app-info -p <你的包名>   # 应用详情与版本列表

// project list 输出示意（ID 已脱敏）
{ "projectList": [ { "projectId": "<projectId>", "name": "<项目名>" } ], "ret": { "code": 0 } }

约定：appId 取 .appids[0].value，projectId 取 project list，certId 取 cert-create，provisionId 取 profile-create。不要从文档里抄一个旧 ID 贴进命令。

3. 证书与 Profile：发布证书不绑设备，调试证书要绑

签名材料是上架第一道硬门槛。三件套（.p12 + .cer + .p7b）必须成套同源，且只在当前工程 .certs/ 里找——云侧有证书不代表本地可用，AGC 不下发私钥。

node scripts/connect-api-cli.js provision csr-generate --pwd <用户输入>   # 本地生成 CSR + P12
node scripts/connect-api-cli.js provision cert-create ...                  # type 2 = 发布证书
node scripts/connect-api-cli.js provision profile-create ...               # 发布 Profile 无需设备

// csr-generate 输出示意：只展示关键路径，pwd 字段不展示
{
  "filename": "key_<随机数>.p12",
  "csrPath": ".certs/<随机数>/key_<随机数>.csr",
  "storePath": ".certs/<随机数>/",
  "materialPath": ".certs/<随机数>/material"
}

两点关键差异：

• 发布 Profile 不需要设备，调试 Profile 必须先把设备 UDID 注册进去（device-add）；
• 证书/Profile 的下载地址有有效期，取到立刻落盘，别先去做别的事再回来下载。

4. 构建上传与提审：产物格式与构建模式

这是全流程最容易「假成功」的地方——命令成功 ≠ 打出了能上架的包。

# 上架 / 测试分发：assembleApp + 发布证书 → 产物 .app
# 真机调试：      assembleHap + 调试证书 → 产物 .hap（仅 hdc 安装用）

node scripts/connect-api-cli.js upload file ...   # HarmonyOS 上架只接受 .app

# assembleApp 构建成功示意
BUILD SUCCESSFUL
Artifact: <工程>/build/default/outputs/default/<产物名>.app
Version: <versionName> (<versionCode>)

构建后必须验产物，解包 .app 内 module.json：

node -e "const m=require('./unpacked/module.json'); console.log({buildMode:m.app.buildMode, debug:m.app.debug, vc:m.app.versionCode})"

// 期望输出
{ "buildMode": "release", "debug": false, "vc": <versionCode> }

上传成功后按用途分流：上架提交审核（1-3 个工作日，倒排期）；邀请/公开测试先用 -r 6 上传，再 test pkg-add 绑定，然后 test version-submit。

踩坑与排错

坑 1：上传 .hap 被拒——商店只收 .app

• 现象：上传接口报错或测试分发无法绑定包。
• 根因：.hap 是本地安装格式（hdc 用），商店与测试分发只接受 .app。
• 解法：上架/测试一律 assembleApp（buildMode=release + 发布证书）；只有真机调试才用 assembleHap。

坑 2：buildmode 小写被静默忽略，打出 debug 包

• 现象：构建命令返回成功，上传后表现异常。
• 根因：参数名必须驼峰 buildMode。写成 buildmode 不报错，直接按默认 debug 走。
• 解法：一律 -p buildMode=release，并在构建后解包验 app.buildMode。

坑 3：编译模式 ≠ 签名类型

• 现象：buildMode=release 构建成功，但安装时 not trusted app source 或无法上架。
• 根因：编译成 release，但 products[].signingConfig 仍指向调试材料，产物是「release 编译 + 调试签名」。
• 解法：上架包必须 release 编译 + 发布证书/Profile；装机前解包 .p7b 确认 "type":"debug"；临时切过 signingConfig 的，装完立刻改回。

坑 4：DEVECO_HOME 没设，hvigor 报 00303217

• 现象：00303217 Invalid value of 'DEVECO_SDK_HOME'，但 DevEco 明明装好了。
• 根因：工具文件存在 ≠ 环境变量可用；DEVECO_HOME 在 .env 里，而 hvigor 还要求当前会话导出 DEVECO_SDK_HOME。
• 解法：构建前从 DEVECO_HOME 推 SDK 路径并导出到会话（Windows：$env:DEVECO_SDK_HOME = "$env:DEVECO_HOME\sdk"）。

实测复现（Windows 11 / DevEco Studio 26 / 不导出 DEVECO_SDK_HOME 直接构建）：

> hvigor ERROR: 00303217 Configuration Error
Error Message: Invalid value of 'DEVECO_SDK_HOME' in the system environment path.
> hvigor ERROR: BUILD FAILED in 27 s 341 ms

坑 5：encrypt-pwd 裸跑必失败

• 现象：报「未找到加密密钥目录」。
• 根因：Windows 上 CLI 取不到 HOME，默认目录落到当前工作目录的 .ohos\config，而非用户主目录。
• 解法：显式 --config-dir 指向用户主目录下的 .ohos\config，别用不带参数的同一条命令重试。

坑 6：毫秒时间戳当秒算，证书「过期」到 2030 年

• 现象：证书/Profile 过期时间显示成远未来日期。
• 根因：expireTime / updateTime 是毫秒（13 位），当秒会放大 1000 倍；而本地 token 缓存里的过期时间是秒，两套不能混。
• 解法：统一按毫秒 new Date(ms) 换算，固定 Asia/Shanghai 展示；判断是否过期直接比时间戳，不要拿 UTC 字符串比日期。

结论与适用边界

上架前检查清单（8 条，可照抄）

1. .env 凭证可用，auth status 显示 token 缓存命中；
2. .env 有 DEVECO_HOME，构建会话已导出 DEVECO_SDK_HOME；
3. 签名三件套同源成套（.p12 + .cer + .p7b），位于工程 .certs/；
4. 上架/测试用发布证书（type 2），真机调试才用调试证书（type 1）；
5. 构建参数是 buildMode=release（驼峰）；
6. 上架产物是 .app，且已解包验 buildMode==release、debug==false；
7. 包名已绑定：app-id 查得到且与上传包一致；
8. 删除类操作（证书/Profile/设备）一律先确认名称与 id——不可撤销，删掉在用的会导致已发布应用无法更新。

适用边界

• 受限权限（ACL）审批以天计，不要轮询状态；
• OAuth 模式首次登录必须人工浏览器授权；
• 域名白名单修改消耗配额且不恢复，改前先查余量；
• 测试分发审核节奏快，适合先跑通链路再上架。

证书清单实测输出（cert-list 返回，下载地址与账号信息已脱敏）：

{
  "ret": { "code": 0, "msg": "success" },
  "certList": [
    { "id": "<id-1>", "certName": "数易发布证书",   "certType": 2, "expireTime": 1880644625000 },
    { "id": "<id-2>", "certName": "临境音乐发布证书", "certType": 2, "expireTime": 1882187321000 }
  ]
}

certType: 2 即发布证书（1 为调试证书）；expireTime 是毫秒时间戳——这正是坑 6 的来源。

上架状态查询实测输出（app-info -a <appId>，应用 ID 与开发者名称已脱敏）：

{
  "ret": { "code": 0, "msg": "success" },
  "appInfo": {
    "releaseState": 7,
    "privacyPolicy": "https://agreement-drcn.hispace.dbankcloud.cn/index.html?lang=zh&agreementId=<id>",
    "publishCountry": "CN,AL,IE,...（共 100+ 个国家/地区）",
    "contentRate": "{\"HW\":\"3+\",\"ClassInd\":\"L\"}",
    "developerNameCn": "<开发者名称>"
  }
}

用一条命令即可核对「发布地区、年龄分级、隐私政策托管链接、发布状态」——这些信息在控制台分散在 3 个页面里。

参考资料

官方文档（2026-10-29 逐条核验，均 HTTP 200）

• 发布指引 · 发布 HarmonyOS 应用（AGC 应用上架） — 上架流程与物料要求
• 使用 API 首次发布 HarmonyOS 应用 — 与本文 CLI 链路对应的 API 视角
• harmonyos-agent-skills 仓库（GitCode） — CLI Skill 源码与发版记录（MIT，639 commits）
• Matrix 市场 — 技能版本与安装入口（本文实测版本 1.0.2）

规范与工具

• hmos-connect-api-cli-skill（Matrix 市场安装，自带 CLI，Node 直接运行，无需 npm 安装）

附：产品体验建议

1. 静默参数建议报错：buildmode 这类拼写错误目前会被忽略并打出 debug 包，建议直接报错；
2. encrypt-pwd 默认读取用户主目录的 .ohos\config，减少 Windows 首次必失败；
3. 时间戳直接输出北京时间字符串，避免每个调用方各自换算；
4. 上传接口前置拦截 .hap，并提示「商店与测试分发只接受 .app」；
5. assembleApp 后自动校验 buildMode/debug 并提示验产物结果。

---

把上架流程从「控制台里的逐步点击」重构为「一组可复现的命令」，收益在长期：新人接手看命令就能跑通，出错能定位到具体一步，流程也能写成文档与 CI。这才是 CLI Skill 对发布工作流真正的价值。

---