写完一个 ASCF 元服务，真正麻烦的环节往往在调试、打包和发布阶段。这里记录一次从真机调试到 AGC 上架的完整流程，包含运行方式、调试手段、签名配置、包体积优化和发布审核中容易掉进去的坑。
一、运行元服务的四种方式
1. 真机运行
USB 连接手机后，在 DevEco Studio 中选择设备直接运行，这是最稳妥的方式。手机需要开启开发者模式和 USB 调试，设备通过 hdc（HarmonyOS Device Connector）连接。第一次运行会自动安装并启动元服务。模拟器无法覆盖的场景，比如传感器、相机、NFC，最终都依赖真机验证。
2. 模拟器运行
DevEco Studio 自带模拟器，5.1.1 Beta 以上版本支持 ASCF。模拟器胜在方便，不用频繁插拔手机，但摄像头、蓝牙、NFC 这类能力不可用，完整测试仍然需要真机。
3. 热重载
在运行配置里选择带闪电图标的 entry 再点击运行，修改 css/hxml/js/json 文件后界面会在设备上实时刷新，不用等待重新编译。调 UI 时这套流程效率很高，改 padding 或颜色立刻能看到效果。
环境要求：ASCF 运行时不低于 1.0.10，ASCF Toolkit 不低于 1.0.5，ASCF Plugin 不低于 1.0.4.303。
需要注意，新增或删减 page 需要重新编译，修改 app.json、manifest.json 也需要重跑项目。偶尔热重载后状态异常，冷重启即可恢复。
4. 命令行运行
- ascf run
- ascf run --hot-reload
- ascf run --device-id 123456789
命令行方式更适合 CI/CD：拉代码、装依赖、编译部署都可以在服务器上执行。
二、调试代码的三种手段
1. ASCF 调试器
DevEco Studio 6.0 及以上版本，通过视图 -> 工具窗口 -> ASCF 调试器打开，点击调试按钮会自动拉起 V8 引擎调试。
调试分为两层。视图层是 UI 渲染层，基于 Webview，使用 Chrome DevTools 的 chrome://inspect/#devices，配置 localhost:9222；逻辑层是 V8 引擎，在 DevEco Studio 或 VSCode 里调试。IDE 版本低于 6.0 时，调试页面会在浏览器中打开。
2. 命令行调试
- ascf debugger start
- ascf debugger start -o
- ascf debugger start-view
- ascf debugger start-service
- ascf debugger stop
- ascf debugger status
常用参数包括：--bundleName 指定包名，多应用场景适用；--deviceId 在多设备时指定目标设备；--open 选择 chrome 或 edge 打开调试页；-ct hdc 指定连接类型。
第一次启动调试后容易不知道去哪里看页面，需要打开 Chrome 的 chrome://inspect/#devices，确认 Discover network targets 已勾选，并在 Configure 里添加 localhost:9222 和 localhost:9229。
3. ASCF Console 调试面板
在 ascf.config.json 中加入 enableDevTools 配置，即可在手机上显示调试悬浮窗。
- {
- "enableDevTools": true
- }
这个面板提供三个视图。Console 实时显示 console 日志，支持关键字筛选和分类过滤，长按记录可以复制、置顶或标记；API 显示 has.request 等 API 的调用记录；Storage 可以查看和管理本地缓存，按 key 删除。排查接口请求和缓存问题时非常直观。
但该选项会影响页面加载速度，调试完一定要关闭。曾有项目一直开着它调试，页面明显卡顿，关闭后才恢复流畅。
另外还可以在 DevEco Studio 底部的 Log 面板过滤关键字 006F 或 ascf-app 查看 ASCF 框架日志。如果报错信息是 xxx is not defined，通常意味着该 API 在 ASCF 中还未实现，比如 has.getFileSystemManager 曾在某些版本中不可用，需要到 API 文档确认起始支持版本。
三、签名配置
开发证书与发布证书是两套体系，调试时用开发证书，上架必须用发布证书，不能混用。签名配置写在 build-profile.json5 中。
- {
- "app": {
- "signingConfigs": [
- {
- "name": "release",
- "material": {
- "certificatePath": "./release.cer",
- "keyStorePath": "./release.p12",
- "keyStorePassword": "****",
- "keyPassword": "****",
- "keyAlias": "release"
- }
- }
- ]
- }
- }
常见错误是用调试证书打 release 包，IDE 报证书类型不匹配。明确一点：调试证书和发布证书的申请入口不同，发布证书需要到 AGC 上申请。发布证书不是即时生成的，提交后要等待华为审核，建议预留时间，不要临到上架才申请。
四、上架前的元服务信息
标题和描述在 entry/src/main/resources/ 下修改：zh-CN/element/string.json 对应中文信息，base/element/string.json 对应默认英文信息。
图标要求 512x512，放在 AppScope/resources/base/media/app_icon.png。直接拿任意 512 图上传 AGC 会报图标不符合规范，必须使用华为提供的元服务图标生成工具处理。
启动图在 module.json5 中配置，使用 startWindowIcon 和 startWindowBackground 字段。
五、构建发布包
IDE 构建时，将工具链设置中的 Build Mode 改为 release，执行 Build > Build Hap(s)/APP(s) > Build APP(s)，产物在 build/ 目录下。
命令行构建使用 ascf build assembleApp，CI 流程中可以直接复用，产物与 IDE 一致。
六、包体积优化
元服务包体约束：单个分包不超过 2MB，总包不超过 10MB，debug 包不限制。第一次打 release 包时总包到 12MB，直接被拒，以下是实际有效的降体积手段。
先用 ascf compile . -c -m --analyzeBundle 生成 HTML 报告，在浏览器中查看每个分包的大小和依赖关系。基础包超过 2MB 就需要拆分包：普通分包把不常用的页面拆到子包按需加载，异步化分包可以进一步细粒度拆分，到使用时再下载。
- {
- "pages": ["pages/index/index"],
- "subPackages": [
- {
- "root": "pages/detail",
- "pages": ["detail/index"]
- },
- {
- "root": "pages/settings",
- "pages": ["settings/index"]
- }
- ]
- }
图片尽量放在云端 CDN，不要本地引用。本地图片一张 100KB，10 张就占 1MB，图片上云是见效最快的一步。本地残留的图片资源用 WebP 格式替代 PNG，通常能缩小 30% 到 50%。同时检查 dependencies，能不用三方库就尽量不用，优先使用系统 API。
七、发布流程
发布前先对照元服务审核指南做一轮自检，然后打 release 包。在 AGC 上可以先邀请部分测试用户，提前暴露问题。元服务还要做资质审核与备案。提交审核通过后即可上架。
AGC 上有一个是否加密元服务包的选项：加密后安全性更高，但启动时需要解密，会影响即点即用的体验，非特殊安全需求建议不加密。
八、踩坑清单
调试证书打 release 包：IDE 报错不明确，检查 build-profile.json5 中的 signingConfigs，确认为 AGC 申请的发布证书。
热重载不生效：先排查版本，ASCF 运行时、Toolkit、Plugin 是否满足最低要求；修改 manifest.json 和 app.json 不会触发热重载，需要重新运行。
ascf debugger start 后找不到调试页面：在 chrome://inspect/#devices 里检查 Discover network targets，并确认 Configure 中包含 localhost:9222 和 localhost:9229。
enableDevTools 未关闭：调试面板初始化会影响低端机性能，有项目带着 enableDevTools 上线，用户反馈页面加载慢。发布前一定要检查 ascf.config.json。
包大小超限：分包加图片上云最有效，分析报告用 ascf compile . -c -m --analyzeBundle 生成。
AGC 域名白名单未配置：调试阶段不走 AGC 所以发现不了，release 包若未配域名白名单，上线后所有请求都会失败。
启动图在低端机显示慢：不要用高分辨率复杂图片，建议低分辨率加纯色背景。
真机与模拟器权限差异：模拟器跑通不代表真机没问题，例如 NFC 权限声明在两者之间不一致，可能导致真机上闪退。发布前务必在真机完整回归一遍。
从调试到上架，关键节点集中在签名配置、包体积控制和 AGC 配置。把这些问题整理成发布 checklist，后续每次上架按顺序核对，能省掉大量返工时间。 |
发表于 
发表于