Makerizon上架鸿蒙PC全记录：适配到提审踩坑总结

摘要：Makerizon 是我们在做的课程学习平台，功能覆盖课程学习、开发模板与三方库检索。当这套能力要从手机端延伸到鸿蒙PC桌面时，"能跑"和"能上架"之间隔着两道完全不同的关卡：一道是工程侧的PC适配，一道是 AppGallery Connect 侧的资质与提审。本文完整记录 Makerizon 从 PC 适配到通过上架审核的全过程，包含可运行的配置与代码示例、每一步的真实踩坑和解决方案，希望能帮助更多开发者少走弯路。

加入开源鸿蒙PC社区

欢迎加入开源鸿蒙PC社区：https://harmonyyopic.csdn.net/

欢迎在PC社区平台申请适配项目：https://atomgit.com/OpenHarmonyPCDeveloper ，如有相关项目也可以上传至 AtomGit 仓库，与更多开发者一起推进鸿蒙PC生态建设。

---

一、为什么要做鸿蒙PC版

Makerizon 的核心场景是"坐下来学东西"。用户要对着屏幕看课程、翻文档、复制命令、照着模板建工程，这些动作天然更适合在键盘鼠标、大屏窗口的环境下完成。手机端解决的是碎片时间的浏览需求，PC端解决的才是完整的深度使用链路。

因此我们把 PC 端优先级提了上来：同一套课程数据、同一套三方库检索能力，在鸿蒙PC上以桌面窗口的形态提供服务。但在动手之前，我们先明确了两条技术路线。

二、先选路线：原生适配还是兼容分发

这是做鸿蒙PC版本最关键的一次决策，直接决定后续所有工作量。两种路线的对照如下：

维度	原生PC上架	兼容分发到PC
deviceTypes 声明	包含 pc / 2in1	Entry模块中不声明 2in1
AGC 勾选方式	支持设备处勾选 PC/2in1	基本信息中勾选"兼容分发到PC/2in1"
窗口表现	标准桌面窗口，可最大化	固定比例窗口，不支持最大化
适配工作量	需要响应式布局与键鼠适配	少量排查，甚至无需改动
交互体验	鼠标悬停、快捷键、多列布局	手机布局等比拉伸

结合 Makerizon 的实际情况，我们选择了原生PC上架：课程列表、模板库、三方库检索都是典型的"信息密度型"页面，等比拉伸放大后一片空白，用户能直观感觉到敷衍。

踩坑：两条路线互斥。一旦在支持设备处勾选了 PC/2in1，系统兼容能力就不再生效，应用会以原生形态被放到 PC 上接受检验。所以不要"两个都勾上求保险"，那等于直接告诉审核人员：我没有为PC做过适配。

三、工程侧适配

3.1 声明支持的设备类型

所有模块的 module.json5 都要同步修改，不只是 entry 模块：

// entry/src/main/module.json5
{
  "module": {
    "name": "entry",
    "type": "entry",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1",
      "pc"
    ],
    "deliveryWithInstall": true,
    "installationFree": false
  }
}

踩坑：工程里如果有多个 module，每个 module 的 module.json5 都必须包含 pc / 2in1，漏改一个打包产物就会缺制造商配置，安装时可能提示不支持该设备类型。

3.2 响应式断点：让布局跟着窗口走

桌面窗口可以被拖成任意尺寸，固定宽度的布局必炸。我们用媒体查询监听宽度变化，把断点写入全局存储：

// utils/BreakpointSystem.ets
import { mediaquery } from '@kit.ArkUI'

export class BreakpointSystem {
  private smListener = mediaquery.matchMediaSync('(320vp<=width<600vp)')
  private mdListener = mediaquery.matchMediaSync('(600vp<=width<840vp)')
  private lgListener = mediaquery.matchMediaSync('(840vp<=width)')

  register(): void {
    this.smListener.on('change', r => r.matches && this.update('sm'))
    this.mdListener.on('change', r => r.matches && this.update('md'))
    this.lgListener.on('change', r => r.matches && this.update('lg'))
  }

  private update(breakpoint: string): void {
    AppStorage.set('currentBreakpoint', breakpoint)
  }
}

页面侧根据断点切换列数与导航形态：PC 断点下课程模块用三列网格加左侧固定导航，手机断点下退化为单列列表加底部标签栏。

踩坑：断点监听要在 aboutToAppear 里注册，并且监听器对象必须保存在组件生命周期之外，否则组件重建时监听会丢失，导致放大或拖动窗口时布局不跟随刷新。

3.3 键鼠交互适配

这是最容易漏掉的一环。PC用户不会用手指去"点"，他们用悬停、滚轮和右键。Makerizon 为所有可点击的卡片与列表项补充了鼠标悬停态（背景色轻量变化 + 边框提亮），列表全部支持滚轮滚动，三方库卡片还提供了右键菜单直达"复制安装命令"。

踩坑：悬停态这类交互视觉变化必须通过 @State 状态变量驱动，直接在 build 里写死样式不会触发重绘；另外滚轮与悬停在模拟器里测不全，一定要上真机验证。

另外，PC端所有图片资源和字体单位统一使用 vp/fp，高分屏下不会出现图标发虚；窗口最小尺寸要在 module 中显式约束，避免用户把窗口拖到极窄时出现控件重叠。

四、调试与环境验证

先用 DevEco Studio 的本地模拟器跑通全部页面，再上真机。这里有一个官方提供的实用技巧：应用安装到电脑后，进入"设置 → 显示和亮度 → 应用显示布局"，把显示比例调整为原始比例，即可退出兼容模式，方便直接观察原生布局的真实表现。

踩坑：模拟器与真机的窗口管理行为有差异，多窗口并排时PC端会按窗口实际尺寸而非屏幕尺寸计算断点，这个细节模拟器里几乎测不出来，提审前务必在真机上把"窗口拖窄—恢复—最大化"完整走一遍。

五、上架前的资质准备

功能跑通只是开始，上架真正卡时间的是材料和合规环节。我们整理了一份清单：

材料	说明	Makerizon 实际处理
开发者实名认证	个人用身份证，企业用营业执照，未实名无法发布	上线前两个月完成
APP备案	按工信部要求取得备案号，服务器在大陆选大陆类	提前办理，确保信息一格不差
软件著作权	非强制，但可有效保护应用名与应对纠纷	已申请，名称与上架名完全一致
隐私政策链接	应用内与商店页同时可达	独立页面托管
图标与截图	提交图标、桌面图标、最近任务列表图标三者一致	统一同一套资源
测试账号	涉及登录时必须提供	备注区提供长期有效账号

踩坑：备案信息、软著名称、AGC 上填写的应用名称必须三方完全一致，包含标点和大小写。我们最初在其他平台备案时带过尾部后缀，导致校验不通过，最后是在 AGC 端按备案名回改才解决。这块建议在项目启动第一天就一次性统一命名。

踩坑：企业主体上架时，软著证书上的著作权人必须与AGC开发者账号的实名主体（营业执照信息）完全一致；如果软著登记在另一家公司或个人名下，必须走完授权流程——授权书需包含授权双方信息、授权应用名称、细则、期限并加盖公章，个人授权方还需附手写签名与身份证扫描件。这些材料建议提前备齐，不要等提审前一晚才发现缺。

六、签名、打包与AGC提审

流程按以下顺序走：

1. 在 DevEco Studio 生成密钥与证书请求文件（.p12、.csr）
2. 在 AppGallery Connect 申请发布证书与 Profile（用到 ACL 权限时需先申请 ACL 权限再生成 Profile）
3. 打包生成 App Pack（.app 文件）
4. 上传软件包，执行合法性检测与上架自检
5. 逐项填写发布信息：基础信息、支持设备、隐私与AI声明、资质材料、联系信息
6. 确认版本号无误后提交审核

踩坑：AGC 后台勾选的支持设备范围，绝对不能大于软件包 deviceTypes 声明的范围。声明 ["phone","tablet","2in1","pc"] 却只勾选手机是允许的；反过来声明只有 phone 却在后台勾选 PC，提交审核时会被系统直接拦截，提示软件包与声明支持设备不一致。

踩坑：上传包前务必跑一次上架自检（云测试），它对兼容性、稳定性、性能、功耗、UX、隐私做自动化检测并输出报告。我们在自检阶段就发现了一个窗口极端尺寸下的布局崩溃，这个Bug如果被审核人员抓到，至少多一轮驳回。

七、审核避坑与时效

Makerizon 整体提审节奏如下：正式版本审核通常在 1–3 个工作日完成，多数在 24 小时内出结果；邀请测试版本工作时间内提交一般 3 小时左右。遇到线上严重Bug需要紧急修复，可以在后台申请审核加急，但要珍惜加急资源。

几个高频驳回点：

• 图标不一致：提交图标、安装后桌面图标、最近任务列表图标必须完全相同，不得使用系统默认图标
• 应用名称冲突：创建时系统会校验唯一性，但通过校验不代表安全，审核团队还会判泛词与侵权风险
• 第三方账号登录：若应用支持三方账号登录，必须同时提供华为账号登录选项
• 功能描述不符：简介里写到的功能必须都能实际走通，审核会逐项验证
• AI相关能力：涉及生成式AI需提供生成合成内容标识材料与算法备案信息

上架后如果用户在应用市场搜不到，按三个维度排查：设备系统版本是否为 HarmonyOS 5 及以上、设备 API 版本是否在适配范围内、应用包是否发布了该设备类型——只发手机的包在PC端就是搜不到的。

八、总结

从"手机上一个好用的课程平台"到"鸿蒙PC上可上架的桌面应用"，中间隔着的是工程适配和合规流程两件事。Makerizon 的这次实践告诉我们：

1. 路线要先选清楚：原生PC上架和兼容分发二选一，不能两勾求保险
2. 响应式不是可选项：窗口可被拖成任意尺寸，断点系统是PC版的地基
3. 键鼠交互是隐性门槛：悬停态、滚轮、复制粘贴决定了桌面体验的下限
4. 资质材料提前备：备案名、软著名、AGC应用名必须完全一致
5. 提审前跑自检：上架自检（云测试）能提前拦下绝大多数驳回原因
6. 设备勾选要克制：后台范围可以小于工程声明，绝不能大于

上架不是终点。Makerizon 上架后我们建立了崩溃监控与用户反馈回收机制，按周迭代小版本，并根据 PC 用户的使用习惯持续调整信息密度与键盘操作路径。如果你也正在做鸿蒙PC适配，欢迎在评论区交流踩坑经验。