# jd-miniprogram-ci

**Repository Path**: CloudSite/jd-miniprogram-ci

## Basic Information

- **Project Name**: jd-miniprogram-ci
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 京东小程序 CI 脚本操作文档

基于官方 [`jd-miniprogram-ci`](https://www.npmjs.com/package/jd-miniprogram-ci) 封装的命令行脚本，**无需打开开发者工具**即可完成小程序代码的**预览**与**上传（自动设为体验版）**，支持本地一键运行和 CI/CD 流水线集成。

- 预览：生成预览二维码，用京东 App 扫码进行真机调试
- 上传：将本地代码包上传为开发版本并自动设为体验版，返回体验版二维码

---

## 一、环境要求

| 项 | 要求 |
|---|---|
| Node.js | 建议 16 及以上（已在 Node 24 实测） |
| 包管理器 | npm（仓库已内置 package.json） |
| 运行系统 | macOS / Windows / Linux |
| 上传秘钥 | 需小程序管理员在控制台获取 |

安装依赖（首次使用执行一次）：

```bash
npm install
```

---

## 二、目录结构

```
jd/
├── package.json                 # 依赖与 npm 命令
├── .gitignore                   # 已忽略 node_modules 和含秘钥的 ci.config.js
├── README.md                    # 本文档
└── script/
    ├── ci.config.example.js     # 配置模板（可提交到仓库）
    ├── ci.config.js             # 本地配置（含秘钥，禁止提交，需自行创建/填写）
    ├── utils.js                 # 公共模块：参数解析、配置校验、退出码守卫
    ├── preview.js               # 预览脚本
    └── upload.js                # 上传脚本
```

---

## 三、快速开始

### 1. 获取上传秘钥

登录 [京东小程序控制台](https://mp-console.jd.com/)，进入：

**设置 → 开发设置 → 小程序代码上传秘钥**，复制秘钥。

> 秘钥拥有预览、上传权限，请妥善保管，切勿提交到代码仓库。

### 2. 创建并填写本地配置

复制模板生成本地配置文件：

```bash
cp script/ci.config.example.js script/ci.config.js
```

编辑 `script/ci.config.js`：

```js
module.exports = {
  privateKey: '你的小程序代码上传秘钥', // 必填
  projectPath: './dist',               // 必填，小程序构建产物目录
  ignores: ['node_modules/**/*'],      // 选填，打包忽略规则
  uv: '1.0.0',                         // 选填，上传默认版本号
  desc: '',                            // 选填，上传默认备注
  robot: 1,                            // 选填，CI 机器人编号 1~30
}
```

> `script/ci.config.js` 已在 `.gitignore` 中，不会被提交。

#### 如何确定 `projectPath`（重点）

判断标准只有一条：**指向包含 `app.json` 的那个目录**，即小程序代码包根目录，而不是工程仓库根目录。脚本不会自动扫描子目录，工程目录名必须写进路径。

- **路径基准**：相对路径统一以本仓库根目录（`jd/`）解析，不是相对于 `script/` 目录；也支持绝对路径。
- **原生小程序工程**（如工程目录名为 `my-app`，`app.json` 直接在工程根目录）：

  ```
  jd/
  ├── script/
  └── my-app/
      ├── app.json      ← projectPath 填 './my-app'
      ├── app.js
      └── pages/
  ```

- **Taro / uni-app 等跨端工程**（`app.json` 在构建产物 `dist` 中，需先执行构建）：

  ```
  jd/
  ├── script/
  └── my-app/
      ├── src/          ← 源码目录，不能填这里
      └── dist/
          └── app.json  ← projectPath 填 './my-app/dist'
  ```

  即：`projectPath` 的值 = 从 `jd/` 出发到 `app.json` 所在目录的相对路径。

- **自检方法**（能打印出文件即路径正确）：

  ```bash
  ls my-app/app.json         # 原生工程
  ls my-app/dist/app.json    # Taro / uni-app 工程
  ```

### 3. 执行命令

```bash
# 预览：终端直接显示二维码，京东 App 扫码真机调试
npm run preview

# 上传：上传为开发版本并自动设为体验版
npm run upload
```

---

## 四、命令详解

### 4.1 预览 preview

```bash
npm run preview
# 或
node script/preview.js
```

| 参数 | 必填 | 说明 |
|---|---|---|
| `--privateKey <key>` | 否 | 上传秘钥（默认取配置文件或环境变量 `JD_PRIVATE_KEY`） |
| `--projectPath <path>` | 否 | 小程序代码目录（默认取配置文件或环境变量 `JD_PROJECT_PATH`） |
| `--ignores <pattern>` | 否 | 打包忽略规则，可重复传入 |
| `--qrcode <fmt>` | 否 | 二维码格式：`terminal`（默认，终端打印）/ `image`（仅返回 URL）/ `base64`（返回 URL 并在项目根目录保存 png） |
| `-h, --help` | 否 | 查看帮助 |

示例：

```bash
node script/preview.js --qrcode image
node script/preview.js --projectPath ./dist --ignores 'node_modules/**/*' --ignores 'mock/**/*'
```

### 4.2 上传 upload

```bash
npm run upload
# 或
node script/upload.js
```

| 参数 | 必填 | 说明 |
|---|---|---|
| `--privateKey <key>` | 否 | 上传秘钥（默认取配置文件或环境变量 `JD_PRIVATE_KEY`） |
| `--projectPath <path>` | 否 | 小程序代码目录（默认取配置文件或环境变量 `JD_PROJECT_PATH`） |
| `--uv <version>` | 否 | 版本号，格式如 `1.0.0`（默认取配置文件，缺省 `1.0.0`） |
| `--desc <text>` | 否 | 版本备注（默认取配置文件） |
| `--robot <n>` | 否 | CI 机器人编号，整数 1~30（默认取配置文件，缺省 1） |
| `--ignores <pattern>` | 否 | 打包忽略规则，可重复传入 |
| `--qrcode <fmt>` | 否 | 二维码格式：`terminal` / `image` / `base64` |
| `-h, --help` | 否 | 查看帮助 |

示例：

```bash
# 指定版本号与备注上传
node script/upload.js --uv 1.0.1 --desc '修复下单页提交问题'

# 指定机器人与代码目录
node script/upload.js --uv 1.0.1 --robot 2 --projectPath ./dist
```

### 4.3 配置优先级

当同一配置项在多处出现时，优先级从高到低为：

```
命令行参数  >  环境变量（JD_PRIVATE_KEY / JD_PROJECT_PATH）  >  script/ci.config.js
```

---

## 五、CI/CD 流水线集成

流水线中**不要使用本地配置文件**，通过环境变量传入秘钥即可。

### 5.1 GitHub Actions 示例

```yaml
name: Deploy JD Mini Program

on:
  push:
    branches: [main]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install & Build
        run: |
          npm ci
          npm run build:jd        # 替换为你项目实际的构建命令

      - name: Upload
        run: node script/upload.js --uv "${{ github.ref_name }}" --desc "${{ github.event.head_commit.message }}"
        env:
          JD_PRIVATE_KEY: ${{ secrets.JD_PRIVATE_KEY }}
          JD_PROJECT_PATH: ./dist
```

> 需在仓库 **Settings → Secrets and variables → Actions** 中添加 `JD_PRIVATE_KEY`。

### 5.2 Jenkins 示例

```bash
npm ci
npm run build:jd
JD_PRIVATE_KEY="$JD_PRIVATE_KEY" node script/upload.js \
  --uv "$BUILD_NUMBER" \
  --desc "Jenkins #$BUILD_NUMBER"
```

### 5.3 代理配置（企业内网）

工具会自动检测系统代理，也可通过环境变量配置：

| 环境变量 | 说明 | 示例 |
|---|---|---|
| `HTTP_PROXY` / `http_proxy` | HTTP 代理 | `http://proxy.company.com:8080` |
| `HTTPS_PROXY` / `https_proxy` | HTTPS 代理 | `https://proxy.company.com:8080` |
| `no_proxy_ci` | 免代理域名，逗号分隔 | `.jd.com` |

```bash
export HTTPS_PROXY=http://proxy.company.com:8080
export no_proxy_ci=.jd.com
npm run upload
```

---

## 六、退出码说明

| 退出码 | 含义 |
|---|---|
| `0` | 执行成功，已生成预览/体验版二维码 |
| `1` | 执行失败（秘钥缺失、目录不存在、参数非法、打包失败、网络/鉴权失败等） |

脚本内置了**退出码守卫**：官方包在本地校验失败（如缺少 `app.json`）时会异常地以退出码 `0` 终止，脚本会将其纠正为 `1`，确保流水线不会误判成功。失败时可加 `DEBUG=1` 查看完整错误堆栈：

```bash
DEBUG=1 npm run preview
```

---

## 七、常见问题（FAQ）

**Q1：提示 `未找到配置文件 ci.config.js`？**
A：执行 `cp script/ci.config.example.js script/ci.config.js` 后填入秘钥；或直接通过环境变量 `JD_PRIVATE_KEY` 传入。

**Q2：提示 `projectPath 目录不存在`？**
A：请先完成小程序构建生成产物目录（如 `dist`），或修改配置文件中的 `projectPath` 指向正确目录。

**Q3：提示 `未找到 app.json 文件`？**
A：`projectPath` 指向的不是小程序代码根目录，请确认该目录下包含 `app.json`（Taro 项目通常指向 `dist`）。

**Q4：上传/预览鉴权失败？**
A：检查秘钥是否正确、是否过期；确认当前操作账号有该小程序的开发权限，必要时到控制台重新生成秘钥。

**Q5：终端二维码显示乱码？**
A：可改用 `--qrcode image` 获取二维码链接，或 `--qrcode base64` 在项目根目录保存二维码 png 图片。

**Q6：如何忽略更多文件？**
A：在配置文件 `ignores` 数组中追加 glob 规则，或命令行多次传入 `--ignores`。以 `.` 开头的隐藏文件（如 `.git`）默认已被忽略。

---

## 八、相关链接

- 京东小程序 CI 工具官方文档：https://mp-docs.jd.com/doc/miniapp/dev/devtools/2743
- jd-miniprogram-ci（npm）：https://www.npmjs.com/package/jd-miniprogram-ci
- 京东小程序控制台：https://mp-console.jd.com/