【三国志 App 实战系列 20】HarmonyOS 发布前工程检查：Hvigor 构建、真机日志与 CSDN 素材闭环

原创已于 2026-06-21 19:43:05 修改 · 134 阅读

2 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#HarmonyOS #ArkTS #ArkUI #DevEco Studio #移动开发

于 2026-06-21 18:17:16 首次发布

HarmonyOS 专栏收录该内容

1 篇文章

订阅专栏

第二轮第 20 篇不再讲单个页面功能，而是把前 19 篇积累下来的工程动作收束成一张发布前检查表：应用能不能发版、文章能不能发布、截图和日志证据是否闭环，要分开判断。

当前系列文章所述应用《耳畔三国·将星落》已上架鸿蒙应用商店，欢迎各位天才程序员尝鲜、吐槽！

一、真实问题背景：发布不是点一下按钮

前面几篇文章分别处理了内容模型、地图全屏、深浅色跟随系统等具体问题。到第 20 篇时，最容易被忽略的问题反而不是某个 ArkUI 组件，而是发布前的“证据链”是否完整。

这一次的真实场景是：第 19 篇已经在 CSDN 创作中心内容管理页显示 原创 / 高质量，所以第 20 篇可以继续；但本地应用构建在 Hvigor 阶段暴露出 SDK 组件缺失。也就是说，文章发布流程可以继续，应用发版流程必须暂停。

这个判断不能混在一起。技术文章可以记录问题、解释边界、给出复现命令；应用正式发版则必须等构建链路恢复。本文的核心就是把这两条线拆清楚。下面这张首页截图来自当前项目的真实 App 截图，用来说明发布检查关联的是《耳畔三国·将星落》当前版本，而不是脱离项目的流程模板。

耳畔三国 App 浅色首页状态

二、目标与边界：检查的是交付条件，不是粉饰结果

本轮检查目标分成四类：

检查项	目标	本轮结论
上一篇线上质量	内容管理页显示 `高质量`	第 19 篇通过，可继续第 20 篇
本地文章结构	`tools/check_csdn_article_quality.js 20` 达到 92+	写稿后复核
应用构建	Hvigor 能完成 `assembleHap`	SDK 组件缺失，应用发版暂停
素材闭环	封面、正文图、日志、队列字段可追踪	本文补齐

边界也要写明：本文不是 AppGallery 提审教程，不会把构建失败包装成“已通过”；也不是 CSDN 公开 QC 分数追分记录。CSDN 高质量闸门只看创作中心内容管理列表里的 高质量 标识，公开 QC 数字只作为诊断信息。

三、源码对象：这次检查盯住四个文件

第 20 篇的源码对象不是某一个 UI 页面，而是发布链路里的四类文件：

3.1 构建入口只判断任务是否还可执行

hvigorfile.ts 不适合写复杂逻辑。它在检查清单里的作用是确认工程仍然使用官方 Hvigor app task，没有被临时脚本或个人机器路径污染。只要这个入口保持简单，后续排查就能把注意力放在 SDK、模块配置和源码错误上。

3.2 产品配置只公开非敏感片段

build-profile.json5 里包含签名材料路径和加密字段。写文章时必须摘取产品、SDK、strictMode、modules 这些可公开信息，不能为了代码块完整而把签名配置整段粘贴出去。发布检查的一部分，就是判断哪些证据能公开，哪些只能本地留档。

3.3 发布队列记录的是平台验证结果

publish-queue.json 不能变成“我准备发布”的愿望清单。它应该记录已经验证过的事实：文章 ID、成功页、公开页、图床地址、内容管理页高质量标识和复核时间。这样下一轮自动化才能从事实出发，而不是重复猜测上一篇是否合格。

hvigorfile.ts
build-profile.json5
tools/check_csdn_article_quality.js
doc/skills/csdn-publishing/publish-queue.json

根目录 hvigorfile.ts 只做一件事：把系统任务交给 @ohos/hvigor-ohos-plugin。这类文件越薄越好，发布检查时重点不是改它，而是确认它是否仍能驱动工程构建。

import { appTasks } from '@ohos/hvigor-ohos-plugin';

export default {
  system: appTasks,
  plugins: []
}

build-profile.json5 则描述产品、SDK 版本、严格模式和模块清单。公开文章里只展示非敏感部分，签名材料路径、密码字段不应该原样贴出。

{
  "products": [
    {
      "name": "default",
      "targetSdkVersion": "6.1.0(23)",
      "compatibleSdkVersion": "6.0.0(20)",
      "runtimeOS": "HarmonyOS",
      "buildOption": {
        "strictMode": {
          "caseSensitiveCheck": true,
          "useNormalizedOHMUrl": true
        }
      }
    }
  ],
  "modules": [
    { "name": "entry", "srcPath": "./entry" },
    { "name": "library1", "srcPath": "./library1" },
    { "name": "library2", "srcPath": "./library2" }
  ]
}

四、本地质量脚本：先证明文章文件存在

项目里的 tools/check_csdn_article_quality.js 是文章发布前的结构预检脚本。它不会替代 CSDN 后台高质量标识，但可以提前挡住明显不合格的本地稿件。

脚本入口先解析文章编号，如果第 20 篇文件还没创建，会直接失败：

function findArticleFile(input) {
  const no = String(input).padStart(2, '0');
  const fileName = fs.readdirSync(SERIES_DIR)
    .find((name) => name.startsWith(`${no}-`) && name.endsWith('.md'));
  if (!fileName) {
    throw new Error(`Article ${input} not found under ${SERIES_DIR}`);
  }
  return path.join(SERIES_DIR, fileName);
}

本轮写稿前先跑了一次，得到的结果正好说明发布素材闭环的第一步就是“本地稿件必须存在”：

node tools/check_csdn_article_quality.js 20


& "D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\node\node.exe" tools\check_csdn_article_quality.js 20

这个失败不是坏事，它给自动化流程一个明确起点：先生成草稿、封面、正文图，再重新跑预检。

五、Hvigor 构建探测：把环境问题和代码问题分开

HarmonyOS 项目真正发版前，assembleHap 仍然是必须检查的动作。本机没有把 Hvigor 放进 PATH，所以先定位 DevEco Studio 自带命令：

Get-ChildItem -Path "D:\HuaweiDevelopFormalStudy\DevEco Studio" -Recurse -Filter hvigorw* |
  Select-Object -First 20 FullName

定位到的真实路径是：

D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw
D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw.bat
D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw.js

直接执行批处理时，当前 shell 报 Access is denied。于是绕过批处理，用 DevEco Node 调 hvigorw.js：

& "D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\node\node.exe" `
  "D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw.js" `
  assembleHap --mode module -p product=default --no-daemon

第一次进入 Hvigor 后报 DEVECO_SDK_HOME 无效；设置 SDK 根目录后，构建继续推进到 SDK 组件校验，但最终失败：

00303168 Configuration Error
Error Message: SDK component missing.

Try the following:
  Please verify the integrity of your SDK.
  Please update the SDK at the download link below.

这条日志很关键：它说明当前不是 ArkTS 代码编译失败，也不是 build-profile 模块声明缺失，而是本机 SDK 组件不完整。应用发版要暂停，先修 SDK；文章可以记录这个真实阻塞。

六、真机和截图素材：文章证据不能只靠文字

发布检查还要看截图是否来自当前项目。本文复用当前工程真实 App 截图，展示《耳畔三国·将星落》的深色首页状态；它不是封面，也不是外部素材。构建日志证据放在第八节的命令和输出块里，避免为了截图而上传一张脱离 App 场景的装饰图。

耳畔三国 App 深色首页状态

截图的意义不是“好看”，而是证明文章讨论的对象确实来自当前 HarmonyOS 应用。对于发布前检查类文章，正文图通常至少要覆盖两类证据：

图片类型	作用	注意点
App 真实截图	证明当前项目和用户界面状态	不用旧项目、不用纯封面
日志/管理页截图	证明构建、审核或高质量状态	标明时间和结论，不追公开 QC 分

如果后续要做 AppGallery 提审，还应补充真机安装和关键页面截图，例如：

hdc install -r .\entry\build\default\outputs\default\entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.recordofthreekingdoms
hdc hilog | Select-String -Pattern "EntryAbility|MainFrame|Theme"

本轮因为 Hvigor 阶段已经被 SDK 组件挡住，所以没有继续安装 HAP。这也是发布检查的价值：越早发现环境阻塞，越少制造无效验收。

七、CSDN 队列字段：只在验证后写发布状态

publish-queue.json 是自动化发布的状态账本。它记录文章编号、发布时间、CSDN 图床地址、公开 URL 和质量闸门来源。

第 19 篇已经记录了关键字段：

{
  "no": "19",
  "status": "published",
  "articleId": "162163639",
  "qualityBadgeActual": "高质量",
  "qualityGateSource": "CSDN creation center content-management high-quality badge",
  "reviewStatus": "success page showed 发布成功！正在审核中; public page accessible/审核中 and content-management row shows 原创 / 高质量 / 待审核"
}

第 20 篇发布后也应该补齐这些字段：

{
  "no": "20",
  "status": "published",
  "articleId": "...",
  "successUrl": "https://mp.csdn.net/mp_blog/creation/success/...",
  "publicUrl": "https://blog.csdn.net/wangji93/article/details/...",
  "coverUrl": "https://i-blog.csdnimg.cn/direct/...",
  "bodyImageUrl": ["https://i-blog.csdnimg.cn/direct/..."],
  "qualityBadgeActual": "高质量",
  "qualityGateSource": "CSDN creation center content-management high-quality badge"
}

注意顺序：不是保存草稿成功就写 published，也不是公开 QC 数字到了某个分数才放行。成功页、公开 URL、标题无乱码、内容管理页 高质量 标识都确认后，队列才算闭环。

八、调试命令与日志观察

本轮真实运行过的命令可以压缩成一组发布前检查命令：

8.1 先查本地，再进平台

我的执行顺序固定为：先 git status --short，再读队列和提纲，再复核上一篇线上高质量标识，最后才写新稿。这样做的好处是，如果上一轮文章还没有高质量标识，本轮就不会继续制造新文章，而是回到上一篇原地修稿。

git status --short
rg -n "appTasks|strictMode|modules|PASS_SCORE|qualityBadgeActual|qualityGateSource" `
  hvigorfile.ts build-profile.json5 tools/check_csdn_article_quality.js doc/skills/csdn-publishing/publish-queue.json
& "D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\node\node.exe" tools\check_csdn_article_quality.js 20

构建环境检查命令：

8.2 构建失败要保留第一现场

这次 .bat 被拒绝、DEVECO_SDK_HOME 无效、SDK 组件缺失是连续出现的三个环境信号。保留它们比只贴最后一行 BUILD FAILED 更有价值，因为后续修复时可以按顺序确认：批处理执行策略、Node 路径、SDK 根目录、SDK 组件完整性。

$env:DEVECO_SDK_HOME = "D:\HuaweiDevelopFormalStudy\DevEco Studio\sdk\default"
& "D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\node\node.exe" `
  "D:\HuaweiDevelopFormalStudy\DevEco Studio\tools\hvigor\bin\hvigorw.js" `
  assembleHap --mode module -p product=default --no-daemon

线上发布闸门检查命令不是接口调用，而是打开创作中心内容管理页：

https://mp.csdn.net/mp_blog/manage/article

目标行：第 19 篇
状态：原创 / 高质量
结论：上一篇通过，可以继续第 20 篇

这些命令能回答三个问题：工作区有没有未知改动，文章稿件结构是否过线，构建工具链是否可用。三者缺一项，都不要急着点发布或提审。

8.3 平台验证只看目标行

CSDN 内容管理页可能同时显示阅读、点赞、审核中、同步多平台等很多字段。自动化复核时不要被这些字段带偏，只需要在目标文章行确认标题、原创标识和 高质量 标识。若登录失效、扫码、验证码或页面不可访问，就停止并报告人工处理，不能用公开 QC 页面绕过后台复核。

九、问题复盘：为什么不能只看最后一个成功页面

本轮最容易误判的地方有三个。

第一，CSDN 成功页不等于高质量完成。成功页只能说明发布动作被平台接收，是否达到高质量仍要回内容管理列表看目标行是否显示 高质量。

第二，公开 QC 数字不是本项目的发布闸门。前面几篇已经遇到过后台 高质量 与公开 QC 分数不一致的情况，因此本文继续遵守内容管理页标识优先。

第三，Hvigor 构建失败不能一概归因于代码。当前日志明确指向 SDK component missing，修复动作应该是检查 DevEco SDK 组件完整性，而不是盲目改 ArkTS 页面或 build-profile。

十、工程验收清单

验收项	命令或入口	通过标准
工作区状态	`git status --short`	识别已有改动，不误回退
上一篇高质量	CSDN 内容管理页	目标行显示 `高质量`
本地文章预检	`check_csdn_article_quality.js 20`	分数 `>= 92` 且无 blocker
封面素材	`doc/generated_images/csdn-covers/20.png`	与系列风格一致
正文截图	App 截图 + 日志证据图	至少 2 张，能解释上下文
Hvigor 构建	`assembleHap --mode module`	当前失败，需补 SDK 组件后重跑
队列更新	`publish-queue.json`	发布验证后再写 URL 和质量字段

这张表的重点是“真实”。通过就写通过，失败就写失败原因和下一步，不要为了让文章看起来顺利而删掉关键日志。

十一、二次补强：把脚本分数映射到发布决策

第一次发布后，我在内容管理列表看到第 20 篇只显示 原创，没有行内 高质量。这时不应该去追公开 QC 数字，也不应该假设平台稍后一定会补标识，而是要回到文章本身补强可验证工程信息。

本地预检脚本的评分维度已经给了一个很好的补强方向：正文长度、标题层级、代码块、图片、表格、调试命令、复盘和源码对象。高质量文章不是把这些元素堆在一起，而是把它们映射到真实发布决策。

11.1 评分不是结论，字段才是结论

脚本里 PASS_SCORE 只负责本地结构门槛：

const PASS_SCORE = 92;

const result = {
  filePath,
  title: title.replace(/^#\s+/, ''),
  score: finalScore,
  passScore: PASS_SCORE,
  pass: finalScore >= PASS_SCORE && blockers.length === 0,
  blockers,
  findings,
  metrics: {
    bodyLength,
    h2Headings: h2Headings.length,
    h3Headings: h3Headings.length,
    codeBlockCount,
    imageCount,
    tableCount,
  },
};

真正进入队列账本时，要写的是平台验证字段，而不是“我觉得质量不错”：

{
  "localQualityScore": 100,
  "localQualityCheckedAt": "2026-06-21T18:xx:xx+08:00",
  "qualityBadgeActual": "高质量",
  "qualityGateSource": "CSDN creation center content-management high-quality badge",
  "qualityCheckedAt": "2026-06-21T18:xx:xx+08:00"
}

这也是为什么第 20 篇第一次发布后不能直接结束：本地结构预检通过，只说明文章具备发布条件；内容管理列表没有 高质量，就说明线上高质量闸门还没有完成。

11.2 SDK 组件缺失要归类为环境阻塞

本轮 Hvigor 输出里有一段比 BUILD FAILED 更有价值：

Local scan or download HarmonyOS sdk components toolchains,ets,js,native,previewer
00303168 Configuration Error
Error Message: SDK component missing.

这三行可以推导出一个明确判断：Hvigor 已经开始扫描 HarmonyOS SDK 组件，并在组件完整性校验阶段失败。它不是 ArkTS 类型错误，不是模块依赖循环，也不是 module.json5 配置缺页。因此验收清单里应写：

日志信号	分类	下一步
`node.exe` 拒绝访问	本机执行策略/路径问题	改用 DevEco Node
`DEVECO_SDK_HOME` 无效	环境变量问题	指向 DevEco SDK default
`SDK component missing`	SDK 组件完整性问题	修复/更新 SDK 后重跑构建

如果这一步被误写成“代码构建失败”，后续很容易浪费时间去改页面、资源或模块拆分。发布检查文章的价值就在于把失败归类清楚。

11.3 封面、正文图和公开页要能互相指认

发布后检查图片时，我不只看页面上“有图片”，还看正文 HTML 里是否真的出现了这两个当前项目截图 URL：

https://i-blog.csdnimg.cn/direct/bffb2f5134cf4c518dd0f26f94c71f60.png
https://i-blog.csdnimg.cn/direct/e342af76da9341ba9999cc34d83e6d04.png

这能避免两类问题：一是正文里仍然残留本地相对路径，公开页变成断图；二是只上传了封面，正文却没有实际内容图片。对于 CSDN 系列文章，封面负责列表识别，正文图负责解释工程状态，两个职责不能混用。

十二、小结

第 20 篇把系列从功能实现拉回到发布工程：hvigorfile.ts 负责接入构建任务，build-profile.json5 负责描述模块和 SDK 目标，tools/check_csdn_article_quality.js 负责本地文章结构预检，publish-queue.json 负责线上发布状态追踪。

本轮结论也很明确：CSDN 第 19 篇内容管理页已经显示 高质量，第 20 篇可以继续发布；但本机 Hvigor 构建被 SDK component missing 阻塞，应用发版需要先修复 DevEco SDK 组件后再验收。

十三、下一篇衔接

第二轮 11-20 篇到这里完成了从增长入口、备份恢复、生命周期、多模块、资源、搜索、内容模型、地图、主题到发布检查的闭环。下一篇如果继续扩展，我会把重点放到“发布后运营数据如何反哺本地内容结构”：阅读、收藏、反馈入口和后续版本迭代如何在不引入服务器的前提下保持可维护。