# 千岛小程序 CLI

在终端完成项目创建、登录认证和版本上传。本文命令默认使用正式开放平台，已按 0.1.34 核对。

## 安装与配置

安装 CLI，检查版本并查看当前版本支持的命令。

```bash
npm install -g qdmp-cli@latest --include=optional
qdmp-cli --version
qdmp-cli --help
```

### 关联应用

先使用开放平台账号登录 CLI。仅在项目没有 qdmp.json 时，替换 AppID 并初始化配置；文件已存在但 appId 为空时，只补入 AppID 并保留 loader 等其他字段。已有不同 AppID 时先确认目标应用，不要直接覆盖。

```bash
qdmp-cli login

# 仅在项目没有 qdmp.json 时执行
qdmp-cli init -a your_app_id

# 关联后必须验证账号与应用
qdmp-cli getMe
```

AppID 可在正式开放平台控制台获取，本地开发、版本上传和体验版验证均使用同一个 AppID。不要把 AppSecret 放入前端代码或提交到仓库。

## 代码包体积要求

用于上传的压缩代码包体积不得超过 6 MB，以 QDMP CLI 的构建或上传检查结果为准。超过限制时，请先移除未参与运行的文件、重复资源和非必要依赖，并压缩图片等静态资源，再重新构建上传。

## 项目管理

仅支持 2.0（EMP）小程序；不支持 SPA/effuse 工程。查看官方模板，创建项目并初始化应用配置。

### 更新旧 CLI

更新后检查实际运行版本。本文以 0.1.34 为核对版本；Skill 通过原安装渠道单独更新，升级 CLI 不会自动迁移旧项目。

```bash
npm install -g qdmp-cli@latest --include=optional
qdmp-cli --version
qdmp-cli list
```

### 查看模板

查看当前 CLI 提供的模板。

```bash
qdmp-cli list
```

### 创建项目

显式选择 default 官方 2.0 模板，创建后确认 loader 为 EMP；旧 CLI 缺少该模板时先更新。GitHub SSH 失败时使用同一模板的 HTTPS 地址。

```bash
qdmp-cli create my-miniapp -t default
cd my-miniapp
```

### HTTPS 创建项目

本机没有 GitHub SSH 凭据时，从同一官方模板的 HTTPS 地址创建，并移除模板仓库远端。完成后确认 package.json 已生成。

```bash
git clone --depth 1 https://github.com/EchoTechFE/qdmp-taro-template.git my-miniapp
cd my-miniapp
git remote remove origin
```

### 拉取配置

登录 CLI 后，根据 AppID 初始化配置；已有 qdmp.json 时直接核对并复用。appId 为空时只补该字段，不要覆盖其他配置。

```bash
qdmp-cli init -a your_app_id
```

## 登录认证

使用正式开放平台账号登录 CLI，并确认当前账号和关联应用。

### 登录认证

按终端提示选择扫码、浏览器或账号密码登录。使用开放平台用户身份，不使用应用 AppID / AppSecret。

```bash
qdmp-cli login
```

账号信息可前往 [开放平台个人资料页](https://open.qiandao.com/dashboard/profile) 查看。浏览器登录与 CLI 登录分别完成。

### AI Agent 登录

输出登录链接、二维码 PNG 和 JSON 事件，无需终端输入。将链接或二维码交给用户，等待 success 事件后再用 getMe 核对身份；ready 只表示登录入口已生成。

```bash
qdmp-cli login --agent
```

### 查看当前用户

确认当前账号、应用与 loader 一致；2.0 项目必须本地和平台均为 EMP。旧 CLI 不显示类型时先更新或在控制台核对。

```bash
qdmp-cli getMe
```

## 构建与上传

构建方式由模板和 loader 决定；package.json.version 和 SDK 版本不代表小程序代际。2.0 必须完成 EMP 编译，失败不得改走 H5。

### 打包构建

按模板 package.json 执行构建。使用 EMP loader 的项目可运行 qdmp-cli build；上传前确认压缩代码包不超过 6 MB。

```bash
# 查看 CLI 构建选项
qdmp-cli build --help

# 已配置 EMP loader 的项目
qdmp-cli build
```

### 上传版本

在项目目录上传至正式开放平台。版本描述选填，最多 200 字；默认只上传开发版本，不设置体验版或上线。

```bash
qdmp-cli upload --description "本次更新说明"
```

## 体验版与真机调试

体验版使用已上传的版本；debug 从本机提供 EMP 调试包，两者都不会提交审核或正式发布。

### 设置体验版

将 your_version 替换为已上传的版本号。成功后核对返回版本与扫码入口，使用有体验权限的账号验证。

```bash
qdmp-cli experience --version=your_version
```

### 上传并设为体验版

上传成功后将该版本设为体验版；需要结构化结果时添加 --json。--qr-output 可指定一个尚不存在的 PNG 文件。

```bash
qdmp-cli upload --experience --json --qr-output ./experience.png
```

### 真机调试

在 EMP 项目目录启动本地调试服务，保持进程运行并用手机扫码。手机需能访问电脑局域网；多网卡时用 --host 指定可达的本机 IPv4 地址。

```bash
qdmp-cli debug
# 已有 EMP 构建产物时可跳过构建
qdmp-cli debug --no-build
```

## OpenAPI 权限申请

根据已准备的接口使用清单生成申请页面链接，由用户在平台确认并提交申请。此命令不会自动批准权限，也不会扫描代码生成清单。

### 生成申请链接

默认读取 .qdmp/openapi-usage.json。可用 --manifest 指定清单、--app-id 指定目标应用；清单格式见包内 README。

```bash
qdmp-cli openapi apply-url --manifest .qdmp/openapi-usage.json --json
```

## 完整流程

按项目模板完成开发和构建后上传，使用 CLI 设置体验版并扫码验证。提交审核和发布上线在控制台完成。

```bash
# 1. 安装与查看模板
npm install -g qdmp-cli@latest --include=optional
qdmp-cli list

# 2. 创建项目
qdmp-cli create my-miniapp -t default
cd my-miniapp
# 若 SSH 失败，改用 HTTPS 克隆并移除模板远端；确认 package.json 已生成

# 3. 登录并关联应用
qdmp-cli login
# 仅在项目没有 qdmp.json 时执行；空 appId 只补值并保留其他字段
qdmp-cli init -a your_app_id
qdmp-cli getMe

# 4. 开发与构建
# 新模板首次安装可刷新锁文件；已有项目不要自动重写
pnpm install --no-frozen-lockfile
pnpm run dev
pnpm run build

# 5. 使用明确的 CLI 命令构建并上传开发版本
qdmp-cli build
qdmp-cli upload

# 6. 将输出的版本号填入下方，设置体验版并扫码验证
qdmp-cli experience --version=your_version

# 7. 验证完成后，在控制台提交审核并发布
```

上传不会自动完成体验版设置、提交审核或正式发布。请在千岛 App 中验证页面和原生能力。

[查看体验、审核与发布流程](https://open.qiandao.com/docs/version-release.md)

网页：https://open.qiandao.com/docs/backend-ops