HarmonyOS 7 / API 26 DevEco CLI 接入 CI 前怎么查：构建入口、版本锁定和失败报告怎么做

HarmonyOS 7 相关资料里，DevEco Code 和 DevEco CLI 已经不只是“本地开发工具”的概念了。它们更适合放进工程流程里看：代码怎么创建，怎么检查，怎么构建，怎么把失败信息交给团队处理。

我自己更关心的是下面这个场景：本地 DevEco Studio 点运行没问题，但一放到 CI 或另一台电脑上，就开始出现“构建命令找不到、版本不一致、配置文件缺失、失败日志看不出原因”这些问题。

这种问题不能等到上线前再排。更稳的做法是先给工程加一道很轻的自检闸口：不真正打包、不上传、不改线上配置，只检查几个最容易被忽略的入口。

先说这篇解决什么

这篇只处理一个问题：HarmonyOS 7 / API 26 项目准备接 DevEco CLI 或自动化构建前，怎么先确认工程具备可重复构建的基本条件。

我会拆成两组例子：

• 例子一：一个“看起来能跑”的工程，为什么放到 CI 里不稳；
• 例子二：把 CLI 版本、构建脚本、检查脚本和 build-profile 补齐后，怎么让失败信息变得可读。

这里不把 DevEco CLI 写成万能工具。CLI 能做的是把流程固定下来，真正决定稳定性的还是工程里有没有清楚的入口和可复查的配置。

为什么 HarmonyOS 7 项目更应该重视这个

HarmonyOS 7 的开发体验在往工具链和智能辅助方向升级。对单人开发来说，本地工具变强是效率提升；对团队开发来说，真正的价值是让同一套检查可以在不同机器、不同分支、不同环境里重复执行。

如果工程里没有固定入口，问题会很快变成这样：

问题	本地开发时的表现	CI 里的表现
CLI 版本没锁	本机刚好能跑	另一台机器装了新版本，行为变了
build 脚本没写	开发者手动点按钮	CI 不知道该执行哪条命令
build-profile 缺失	IDE 缓存里还能记住配置	干净环境直接找不到 product/buildMode
lint/check 没有入口	小问题混进代码	到构建后半段才爆，定位成本高

所以我会把“能不能构建”拆成两层：

• 第一层：工程是不是具备自动化检查入口；
• 第二层：真实 DevEco CLI 构建命令再接进去。

第一层很轻，但能提前拦掉一批低级问题。

例子一：工程看着有 build，其实还不够

先准备一个不完整工程。它只有 build 脚本，没有声明 DevEco CLI，也没有 build-profile。

{
  "scripts": {
    "build": "echo build"
  }
}

这种工程在本地可能不会立刻暴露问题，因为开发者习惯点 IDE 里的运行按钮。但换到 CI 后，脚本只能看到仓库里的文件，它不知道你本机 IDE 缓存过什么。

我写了一个很小的检查脚本，先检查五件事：

import fs from 'node:fs';
import path from 'node:path';

const root = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();
const checks = [];

function readJson(rel) {
  const full = path.join(root, rel);
  if (!fs.existsSync(full)) return null;
  try {
    return JSON.parse(fs.readFileSync(full, 'utf8').replace(/^\uFEFF/, ''));
  } catch {
    return null;
  }
}

function addCheck(name, ok, detail, fix) {
  checks.push({ name, ok, detail, fix });
}

const packageJson = readJson('package.json');
const buildProfile = readJson('build-profile.json5') || readJson('build-profile.json');

addCheck('package.json 可解析', !!packageJson, packageJson ? '已读取 npm 脚本和依赖声明' : '没有找到 package.json', '补齐 package.json');
addCheck('DevEco CLI 入口明确', !!packageJson?.devDependencies?.['@deveco/deveco-cli'], packageJson?.devDependencies?.['@deveco/deveco-cli'] || '未声明', '固定 @deveco/deveco-cli 版本');
addCheck('构建脚本可被 CI 调用', !!packageJson?.scripts?.build, packageJson?.scripts?.build || '未声明 build 脚本', '增加 build 脚本');
addCheck('质量检查脚本存在', !!packageJson?.scripts?.lint || !!packageJson?.scripts?.check, packageJson?.scripts?.lint || packageJson?.scripts?.check || '未声明 lint/check', '增加 lint 或 check 脚本');
addCheck('HarmonyOS 构建配置存在', !!buildProfile, buildProfile ? '已找到 build-profile 配置' : '没有找到 build-profile', '补齐 build-profile 配置');

跑这个坏样例，输出会直接告诉我失败在哪：

node work/harmonyos7_deveco_cli_ci_guard.mjs work/tmp-harmonyos7-ci-bad

结果里有 3 个失败项：

{
  "passed": false,
  "failedCount": 3,
  "checks": [
    {
      "name": "DevEco CLI 入口明确",
      "ok": false,
      "detail": "未声明"
    },
    {
      "name": "质量检查脚本存在",
      "ok": false,
      "detail": "未声明 lint/check"
    },
    {
      "name": "HarmonyOS 构建配置存在",
      "ok": false,
      "detail": "没有找到 build-profile.json5/build-profile.json"
    }
  ]
}

这个输出比“构建失败”四个字有用。因为它把修复动作也带出来了：先补 CLI 版本，再补检查脚本，再补 build-profile。

例子二：把入口补齐后，CI 才有稳定抓手

再看一个补齐后的样例：

{
  "devDependencies": {
    "@deveco/deveco-cli": "1.2.1"
  },
  "scripts": {
    "build": "deveco build",
    "lint": "deveco check"
  }
}

再配一个最小的 build-profile：

{
  "app": {
    "products": [
      {
        "name": "default"
      }
    ]
  }
}

再跑同一个检查：

node work/harmonyos7_deveco_cli_ci_guard.mjs work/tmp-harmonyos7-ci-good

这次结果是通过：

{
  "passed": true,
  "failedCount": 0,
  "checks": [
    {
      "name": "DevEco CLI 入口明确",
      "ok": true,
      "detail": "1.2.1"
    },
    {
      "name": "构建脚本可被 CI 调用",
      "ok": true,
      "detail": "deveco build"
    },
    {
      "name": "质量检查脚本存在",
      "ok": true,
      "detail": "deveco check"
    }
  ]
}

这里我还查了一下 npm 包信息，当前能查到 @deveco/deveco-cli 的 latest 是 1.2.1，stable 是 1.2.0-stable。文章里不建议所有项目盲目跟 latest，团队更应该锁定一个验证过的版本。

npm.cmd view @deveco/deveco-cli name version dist-tags --json

我会怎么接到真实工程里

如果是一个准备适配 HarmonyOS 7 / API 26 的项目，我不会一上来就把 CI 脚本写得很复杂。第一版只保留三个阶段：

阶段	目标	失败时应该看到什么
precheck	检查工程入口	哪个配置缺了，怎么补
check	做语法、配置、轻量规则检查	哪类代码或配置不符合约定
build	执行 DevEco CLI 构建	哪个 product、buildMode、模块失败

也就是说，CI 不是只跑一条 build 命令，而是先跑一个更便宜的检查：

{
  "scripts": {
    "precheck": "node scripts/harmonyos-ci-guard.mjs",
    "check": "deveco check",
    "build": "deveco build"
  }
}

这样做有两个好处。

第一，失败更早。比如 build-profile 缺了，不需要等完整构建开始以后才报错。

第二，失败更清楚。CI 日志里能看到“DevEco CLI 没固定版本”或者“缺少 check 脚本”，而不是一堆很长的构建输出。

两种方案怎么选

我试过把所有检查都塞进一条构建命令里，但后面维护起来会比较累。更推荐把检查拆开：

方案	做法	适合情况	问题
只跑 build	CI 直接执行构建	小 Demo、个人验证	失败太晚，日志不够直观
precheck + check + build	先查入口，再做质量检查，最后构建	团队项目、活动参赛项目、上架前项目	初期多写一个脚本

我的选择是第二种。多写一个脚本不麻烦，但它能把很多“环境问题”提前暴露出来。

后面还能继续封装什么

这类脚本不应该只检查 package.json。等第一版跑稳后，可以继续加这些检查：

• 检查 compileSdkVersion、compatibleSdkVersion 是否符合当前目标版本；
• 检查 module.json5 里的权限是否和隐私说明一致；
• 检查构建产物目录是否存在；
• 检查关键截图、隐私协议、上架说明材料是否齐全；
• 检查是否有人把本地路径、临时文件、测试地址提交进工程。

这些都不属于炫技，但很实用。HarmonyOS 7 / API 26 项目越往后走，越需要把“本机能跑”升级成“干净环境也能跑、失败原因也说得清”。

最后留一个检查清单

我会把 DevEco CLI 接入前的最低要求收成这 6 条：

• CLI 版本要锁定，不要让每个人机器上跑出不同结果；
• package.json 里必须有统一 build 入口；
• check 或 lint 入口要先于 build 执行；
• build-profile 要进仓库，不能只靠 IDE 缓存；
• CI 日志要输出明确失败项，不要只给一个失败码；
• 升级 HarmonyOS 7 / API 26 前，先跑轻量自检，再跑真实构建。

这样做不是为了把流程搞复杂，而是为了让问题早一点出现、清楚一点出现。对 HarmonyOS 项目来说，工具链升级越频繁，这个基础闸口越值得保留。