京东小程序CI工具实践教学文档

1. 京东小程序CI工具概述

京东小程序CI工具是为京东小程序开发者提供的效率提升工具包，主要功能包括：

• 无需依赖小程序开发者工具即可实现预览、上传等操作
• 支持与构建脚本和流水线结合，实现小程序CI/CD流程
• 提高小程序部署和发布效率

1.1 京东小程序平台简介

• 全面开放的生态模式，可分享京东系APP流量福利
• 架构分为视图层(WebView容器)和逻辑层(JSCore沙箱)
• 通过JSBridge通道进行数据通信

2. 使用前准备

2.1 获取上传秘钥

1. 访问"京东小程序控制台"
2. 进入"设置" → "开发设置" → "小程序代码上传秘钥"
3. 获取并保存上传秘钥

2.2 安装依赖

npm install jd-miniprogram-ci --save

3. 核心功能使用

3.1 上传功能

将小程序上传到京东小程序控制台，生成版本记录，可用于体验版验证和版本提审。

脚本调用方式：

const { upload } = require('jd-miniprogram-ci')

upload({
  privateKey: 'your private key',  // 上传秘钥
  projectPath: 'your project path', // 项目路径
  uv: '1.0.0',                     // 版本号
  desc: '自定义描述信息',           // 描述信息
  base64: false,                   // 控制二维码展示方式
})

命令行调用方式：

jd-miniprogram-ci upload \
  --privateKey your_private_key \
  --projectPath your/project/path \
  --uv '1.0.0' \
  --desc '自定义备注' \
  --base64 false

注意：局部安装时需通过npx或./node_modules/.bin/jd-miniprogram-ci执行

3.2 预览功能

生成临时预览版本用于开发调试，预览版二维码有效期为5分钟。

脚本调用方式：

const { preview } = require('jd-miniprogram-ci')

preview({
  privateKey: 'your private key',
  projectPath: 'your project path',
  base64: false,
})

命令行调用方式：

jd-miniprogram-ci preview \
  --privateKey your_private_key \
  --projectPath your/project/path \
  --base64 false

4. 与流水线集成

4.1 配置上传脚本

1. 在项目根目录新增upload.js文件：

const { upload } = require('jd-miniprogram-ci')

upload({
  privateKey: process.env.PRIVATE_KEY, // 从环境变量获取秘钥
  projectPath: process.cwd(),
  uv: process.env.VERSION,
  desc: process.env.DESC || '流水线自动构建',
  base64: false,
})

2. 修改package.json：

"scripts": {
  "upload": "node upload.js"
}

4.2 流水线配置

1. 参数配置：

   • 将上传秘钥配置为流水线参数
   • 确保秘钥安全性，避免泄漏

2. 新增NodeJS编译原子：

npm install
npm run upload

4.3 工作流程

1. 开发者推送代码到远程仓库
2. 流水线通过webhook监听代码变更
3. 自动下载代码并安装依赖
4. 执行上传脚本完成小程序代码包上传
5. 在小程序控制台查看上传结果

5. 实现原理

5.1 CI客户端流程

1. 使用cac进行命令行参数解析
2. 通过glob进行项目路径匹配
3. 文件压缩处理（跨平台路径兼容）
4. 使用chokidar实现文件监听
5. 上传压缩文件并展示二维码

5.2 CI服务端架构

• 基于Nest.js框架开发
• 封装京东内部中间件(jsf、ump、logbook等)
• 提供打包编译、查询打包ID、生成二维码等接口服务

6. 最佳实践

1. 秘钥管理：

   • 不要将秘钥硬编码在脚本中
   • 使用环境变量或密钥管理服务存储
   • 流水线中使用安全参数传递

2. 版本管理：

   • 建议使用语义化版本控制
   • 可通过环境变量动态设置版本号
   • 在描述信息中包含构建时间或提交ID

3. 错误处理：

   • 添加上传失败的错误处理和通知机制
   • 记录详细的构建日志
   • 设置合理的超时时间

4. 多环境支持：

   • 通过不同秘钥区分测试和生产环境
   • 使用不同描述前缀标识环境
   • 可配置不同的上传参数

7. 常见问题解决

1. 秘钥无效：

   • 检查秘钥是否过期或被重置
   • 确认控制台设置中的秘钥与使用的一致
   • 确保秘钥没有多余的空格或换行

2. 上传失败：

   • 检查网络连接是否正常
   • 确认项目路径是否正确
   • 查看服务端返回的错误信息

3. 二维码不显示：

   • 检查base64参数设置
   • 确认终端支持二维码显示
   • 尝试将二维码保存为图片查看

4. 文件缺失：

   • 检查.jdmpignore配置
   • 确认压缩过程没有报错
   • 验证项目目录结构是否符合要求

8. 进阶使用

1. 自定义构建流程：

   • 在上传前执行代码检查
   • 添加自动化测试环节
   • 集成代码质量分析工具

2. 多小程序管理：

   • 使用配置文件管理多个小程序配置
   • 编写批量上传脚本
   • 实现自动化版本号递增

3. 通知集成：

   • 上传成功后发送邮件或IM通知
   • 与监控系统集成
   • 记录构建历史并提供查询接口

4. 性能优化：

   • 实现增量上传
   • 缓存依赖减少构建时间
   • 并行执行独立任务

通过本教学文档，开发者可以全面了解京东小程序CI工具的功能和使用方法，实现高效的小程序开发和部署流程。