鸿蒙 PC Markdown 编辑器质量流水线：Web 构建、回归与 Release 门禁

仓库出现一份 YAML不等于建立了 CI。质量流水线必须能在干净环境安装固定依赖、构建真实 Web产物、运行回归、把失败传给平台，并明确哪些鸿蒙构建暂时只能在 macOS DevEco环境执行。否则"流水线已配置"很容易被误写成"远程已通过"。

本文基于 OhMarkdown，分析本地统一验证、GitCode Web Runner、缓存、离线产物断言和 Debug/Release门禁，并如实记录当前远程状态。代码位于 https://gitcode.com/VON-/codex_md_oh

先拆平台能力

Web编辑器由 TypeScript、Vite、Playwright构成，可以在 Linux容器执行。HarmonyOS HAP构建依赖 DevEco Studio工具链和 SDK，当前路径在 macOS：

text 复制代码

/Applications/DevEco-Studio.app/Contents

因此流水线分两层：远程 GitCode先承担 Web构建与20项回归；本机统一入口承担 Web、Debug HAP、UnitTestBuild和 diff检查。设备 ohosTest还需要模拟器/HDC。

准确边界比伪造"全平台 CI"重要。Linux Web通过不代表 ArkTS编译和 HAP通过。

Web脚本是最小公共入口

sh 复制代码

#!/bin/sh

set -eu

ROOT_DIR="$(CDPATH= cd -- \
  "$(dirname -- "$0")/.." && pwd)"

cd "$ROOT_DIR/web-editor"
npm run test:e2e

set -e让构建或测试失败立即非零退出；-u拒绝未定义变量。ROOT_DIR从脚本自身位置计算，调用者在哪个目录都一致。

test:e2e本身先 build再 Playwright：

json 复制代码

{
  "scripts": {
    "build": "tsc --noEmit && vite build",
    "test:e2e": "npm run build && playwright test"
  }
}

类型检查、生产构建和测试形成顺序门禁。测试不会只加载开发源码，而是同时生成将打进 HAP的单文件资源。

GitCode Runner 配置

yaml 复制代码

stages:
  - test

web_editor_regression:
  stage: test
  image: mcr.microsoft.com/playwright:v1.61.1-noble
  script:
    - cd web-editor
    - npm ci --ignore-scripts
    - npm run test:e2e
  cache:
    key: web-editor-${CI_COMMIT_REF_SLUG}
    paths:
      - web-editor/node_modules/

Playwright镜像版本与开发依赖 1.61.1对应，减少浏览器二进制不匹配。npm ci严格使用 lockfile，依赖图变化会失败而非静默改写；--ignore-scripts减少安装阶段供应链脚本执行，Playwright浏览器已由镜像提供。

阶段只有 test，任一脚本非零即 job失败。后续可增加 artifact保存 Playwright报告，但报告可能包含测试文档截图，应确保只使用无敏感 fixture。

缓存不是正确性来源

node_modules缓存按分支 slug区分，加速重复执行。npm ci仍根据 lockfile重建所需状态，不能因为缓存存在跳过安装。

更稳 cache key可加入 lockfile哈希和镜像版本。否则依赖变更后旧缓存可能带来非确定行为。首次优化前先测 Runner实际安装耗时；缓存损坏要能删除后重跑。

固定依赖与锁文件

任务列表插件使用精确 2.1.1，其余 CodeMirror和 markdown-it使用兼容范围，但 package-lock.json固定实际版本。流水线只用 npm ci，不执行 npm install更新锁。

依赖升级应单独提交，查看生产 HTML体积、20项回归和安全输出。不能让日常 CI每次拉到新的兼容版本后才发现渲染变化。

产物离线断言

Vite配置：

ts 复制代码

export default defineConfig({
  base: './',
  plugins: [viteSingleFile()],
  build: {
    outDir:
      '../entry/src/main/resources/rawfile/editor',
    emptyOutDir: true,
    sourcemap: false,
    target: 'es2020',
    chunkSizeWarningLimit: 800
  }
});

生产测试读取该 index.html，断言没有外部 script src和 stylesheet link，并包含 OhMarkdownEditor。流水线因此验证的不只是 Vite成功，还锁定离线单文件约束。

如果开发者忘记 build-editor就组装 HAP，旧 rawfile可能进入包。Debug/Release脚本都先执行 build-editor，确保资源新鲜。

本机统一门禁

sh 复制代码

"$ROOT_DIR/scripts/verify-web.sh"
"$ROOT_DIR/scripts/build-debug.sh"

cd "$ROOT_DIR"
"$DEVECO_HOME/tools/hvigor/bin/hvigorw" \
  UnitTestBuild \
  --mode module \
  -p product=default \
  -p module=entry@default \
  -p buildMode=test \
  -p unitTestMode=true \
  --no-daemon

git diff --check

JAVA_HOME和 DEVECO_SDK_HOME从 DevEco路径设置，可由环境变量覆盖。顺序先 Web回归，再 HAP Debug，再测试构建，最后检查补丁空白。

脚本没有运行设备 ohosTest，因此本地门禁成功仍要单独记录4/4设备结果。以后可在检测到目标时执行，不应在没有设备时跳过却显示成功。

Debug 与 Release 都要构建

Debug用于开发安装，Release更接近最终优化和资源打包。两个脚本参数只在 buildMode不同：

sh 复制代码

exec "$DEVECO_HOME/tools/hvigor/bin/hvigorw" \
  assembleHap \
  --mode module \
  -p product=default \
  -p module=entry@default \
  -p buildMode=release \
  --no-daemon

Release当前无签名配置，产物为 unsigned HAP，适合体积和构建验证，不等于可商店发布。签名、证书和流水线密钥属于后续交付安全。

失败必须阻断

shell使用 exec运行 Hvigor，退出码直接成为脚本退出码。Playwright任何断言、TypeScript错误、Vite失败、ArkTS编译错误或 diff whitespace都会使门禁失败。

不使用 || true吞测试。可选清理可以容忍失败，构建与测试不能。流水线页面应将失败 job标红并保留关键日志，不只发聊天通知。

远程状态要如实表达

截至基线，.gitcode-ci.yml已经推送，仓库显示 jobs和 shared runner能力开启，但尚未拿到首次远程成功结果。质量报告状态仍为 In Progress。

在确认平台默认配置文件名、pipeline触发和 Runner日志前，不能写"CI通过"。如果 GitCode实际需要其他文件名或仓库设置，应修正后再记录首个成功 commit、时间和 job链接。

配置存在是输入，远程绿色结果才是证据。文章保留这一差异，避免阶段报告为了完整度伪造状态。

GitCode 与鸿蒙构建的下一步

若获得可运行 DevEco的自托管 macOS Runner，可增加 ArkTS阶段：构建 Web、Debug、Release、UnitTestBuild，缓存 SDK不缓存用户证书。设备测试可连接专用模拟器主机，串行运行避免状态污染。

自托管 Runner涉及机器权限、签名密钥、HDC设备和缓存清理，安全成本高。先让 Web远程稳定，再增加原生，减少同时调试平台和工具链。

鸿蒙 PC 基线版本

下图是流水线与本机门禁保护的实际应用版本。它运行在 MateBook Pro 2in1模拟器，Web资源已离线打入 HAP。

应用截图不证明 CI成功，只证明构建产物进入目标界面。远程 job、构建日志、HAP哈希和设备截图分别承担不同证据。

报告与产物

Playwright失败应保存 trace、截图和 HTML报告，成功可以只保留摘要，控制存储。Release门禁记录 HAP大小和 SHA-256，用于确认交付文件。

测试报告必须包含命令、环境、通过数、失败项和未运行层。不要只写"测试通过"。构建日志中的本机绝对路径和用户信息在公开前清理。

分支与合并策略

远程流水线应对提交和合并请求触发，main保护要求 Web job成功。原生本机门禁在提交前执行并记录。等自托管 Runner稳定后，再把 ArkTS设为强制检查。

紧急修复不能永久绕过门禁；若平台故障允许管理员合并，应在恢复后补跑并记录例外。质量流程要允许故障处理，但不能让例外成为默认。

当前边界

远程首跑未确认；CI只覆盖 Web；没有远程 Release HAP、签名、设备 ohosTest和 artifact策略；cache key未包含 lockfile哈希；内部试用门禁不在自动化流水线中。

这些未完成项正是 G2-08保持进行中的原因。配置文件不能替代外部条件。

流水线自身也需要测试

应定期做受控失败：临时分支加入必然失败的断言，确认 GitCode job确实触发、退出码阻断合并、日志和 artifact可访问；随后撤销测试提交。只观察成功路径无法证明平台没有把脚本失败标成允许失败。

还要验证冷缓存执行，删除 node_modules缓存后从 lockfile完整安装；验证依赖镜像不可用时错误明确；验证并发提交时旧任务取消策略不会把旧绿色状态错误关联到新 commit。每个结果都绑定提交 SHA，而不是只写分支名。

流水线配置变更应像代码一样评审，尤其是 --ignore-scripts、镜像 tag、缓存目录和密钥权限。任何为了"先跑起来"加入的宽松参数都要有到期清理记录。

结语

OhMarkdown流水线从可移植 Web层开始：固定 Playwright镜像、npm ci、类型检查、单文件构建和20项回归。macOS本机入口继续执行 Debug、UnitTestBuild和 diff检查，Release单独验证。每层失败都保留非零退出。

最关键的质量原则是准确命名状态：已配置、已本地通过、已远程通过、已设备通过是四件事。鸿蒙 PC编辑器做大之前，流水线首先要成为可信事实记录，而不是一张装饰性的 YAML。