起因

工程跑通之后,我盯着 module.json5 里那行 deviceTypes 看了很久:

"deviceTypes": ["phone", "tablet", "2in1", "wearable"]

四个设备类型是官方模板默认给的。也就是说,从第一天起,这个工程就"声称"自己能在手机、平板、PC 和手表上跑。但实际上我只在一台模拟器上看过它,还是手机形态。

这行配置给了我很长时间的错觉:我以为跨端是白送的。

真正动手之后才知道,deviceTypes 只是"允许装到哪些设备"的声明,跟"适配得好不好"是两回事。声明一个类型,系统就允许安装;装上去歪不歪、有没有内容溢出,那是另一套问题。

这一篇写两件事:跨端这块我在 CodeArts Agent 里做到哪一步、卡在哪,以及把工程开源出去之前,我在同一个编辑器里做了哪些收尾工作。

为什么还是 CodeArts Agent?因为这两件事恰好是它最擅长的部分——改配置、写文档、跑 git。它们都不需要设备,也不需要签名,全是"文本活"。我前面验证过它的边界:只要不碰设备,它基本能接住。

写之前犹豫过要不要把这两件事放一起。跨端是技术,开源托管是流程,看起来不搭。但它们的共同点很明确:都发生在"功能写完"之后,都决定这个工程能不能交给别人。一个是交给别的设备,一个是交给别的开发者。

deviceTypes 到底管什么

先把这个字段的作用说准。

它写在模块级的 module.json5 里,位置很靠前:

在这里插入图片描述

我一开始以为它是"编译目标",后来发现不是。它更像一份能力声明:这个模块支持哪些设备形态。系统在安装时会核对——如果当前设备类型不在列表里,安装直接拒绝。

四个取值的含义大概是这样:

  • phone:手机,最常规的竖屏形态;
  • tablet:平板,屏幕更大,常见横屏或分栏布局;
  • 2in1:二合一设备,带键鼠、可窗口化,接近桌面体验;
  • wearable:穿戴设备,圆形或小方屏,交互方式完全不同。

这里有个细节值得记住:删掉一个类型,比加上一个类型更省事。 如果你的工程只打算支持手机,就把另外三个删掉,安装时的校验会更严格,也能避免"在平板上装了但布局全乱"的尴尬。

反过来,加上 2in1 很容易,但二合一设备上窗口可以自由缩放,你的布局得扛得住任意宽度。这一条我踩过——具体在下面。

跨端不止是改一个字段

把 deviceTypes 加满,编译、装包都不会报错。但"能装"之后还有三层问题。

第一层是尺寸。 手机是 360 宽,平板可能是 800 宽,2in1 窗口能拉到 1600。你用固定 width(360) 写的布局,在大屏上会变成一小块挤在左边。

第二层是资源。 鸿蒙支持资源限定目录:resources/base、resources/dark、resources/zh_CN、resources/en_US。同一套代码,不同语言和主题取不同的字符串和颜色。跨端不只是屏幕,还包括语言和深色模式。

第三层是交互。 手表上没有"点击",只有长按和滑动;2in1 上有鼠标悬停和右键。同一套逻辑,交互方式得判断设备类型。

我这次只做到了第一层——把布局改成弹性,不写死宽度。第二层留了目录但没填内容,第三层干脆没做,因为手表那端我连设备都没有。

这个取舍是有意的:没有设备验证的适配,等于没做。 与其写一堆"可能在手表上能用"的代码,不如先把手机和平板做好。

改布局的具体做法

原来我的页面是这样:

Column({ space: 14 }) {
  Text('Hello HarmonyOS').fontSize(30)
  Text(`点击次数:${this.count}`).fontSize(20)
  Button('点我 +1').width(160).height(44)
  ForEach(this.items, (item: string) => { Text(item).fontSize(16) })
}
.width('100%').height('100%').justifyContent(FlexAlign.Center)

问题出在 Button 的 width(160) 和文字的固定字号上。在 360 宽的手机上没问题,在 800 宽的平板上看,整个内容会显得又小又空。

改法有两个方向。一是用百分比和 layoutWeight,让内容跟着容器走;二是给不同断点写不同样式。鸿蒙没有 CSS 那种媒体查询,但可以用 display 相关的属性和容器测量来做响应式。

我选了最朴素的一条:把固定尺寸换成上限。按钮用 constraintSize({ maxWidth: 320 }),字体保持不变,靠外层容器限制最大宽度:

Column({ space: 14 }) {
  // ...
}
.width('100%')
.constraintSize({ maxWidth: 520 })

这样在手机上它铺满,在平板上它居中且不会拉得太开。不是最优雅的方案,但改一行就能验证,比引入一套断点系统快得多。

顺便说一句,这个改法只在预览器里验过。真机上会不会有安全区、状态栏遮挡的问题,我没法确认——这也是前面说的"没有设备验证,等于没做"。

资源限定目录:跨端不只是屏幕

鸿蒙的资源目录有一套限定符机制,模板里就带着:

entry/src/main/resources/base/element/string.json    默认
entry/src/main/resources/base/element/color.json     默认
entry/src/main/resources/dark/element/color.json     深色模式

我打开看过,dark/element/color.json 里只有一条:

{
  "color": [
    { "name": "start_window_background", "value": "#000000" }
  ]
}

意思是:深色模式下,启动窗口的背景用黑色。默认目录里对应的是白色。

这就是限定符的用法——同名资源,不同目录给不同值,系统按当前环境自动挑。常见的限定符有:

  • dark / light:深色与浅色主题;
  • zh_CN / en_US:语言与地区;
  • phone / tablet / 2in1:设备形态;
  • 分辨率相关的限定符(按屏幕密度)。

设备形态也能当限定符,这一点很多人不知道。也就是说,跨端可以不只靠代码判断,还能靠资源:给平板准备一套不同的尺寸和间距,系统会自动选。

我这次没这么做,原因是资源翻倍之后维护成本会上来。一个页面本来只有一份 string.json,加了平板限定就变成两份,改文案要改两处。对一个小工程来说,得不偿失。

但如果是正式产品,这套机制很值。它把"适配"从代码里搬到资源里,代码只写逻辑,布局差异交给资源管。这是鸿蒙设计里比较聪明的一块。

码道的技能给了一条现成的边界线

改 deviceTypes 之前,我在拆码道插件时看到过一个技能,叫 harmonyos-ui-multi,描述里有一句话:

当前覆盖手机、折叠屏和平板,不覆盖 2in1/PC。

这句话解决了我一个纠结:四个设备类型都声明了,适配要做到哪一步才算完?

官方技能的答案是:先做手机、折叠屏、平板,2in1/PC 先放。这不是技术限制,是优先级——把三个移动形态做扎实,比四个都做一半有用。

我把这条当成了自己的验收标准:声明四个,但只为前三个负责,2in1 明确标注"未适配"。

这种"从工具里读出来的经验"挺有意思。技能包本来是给 AI 用的,但人去读它的描述,也能得到判断依据。文档很少会写"我们不做什么",技能描述反而愿意写,因为模型需要边界才能不跑偏。

预览器里能看什么

DevEco 的预览器顶部有一排控件,能选设备类型和尺寸,我看过它默认停在 “Phone (width: small, height…)”。截图里就是这个状态。

也就是说,理论上可以在预览器里切到平板尺寸看布局。这一点比真机方便得多,改一行代码就能看到不同尺寸的效果。

但我没在这上面花太多时间,原因是预览器和真机的差异在前面已经吃过一次亏——预览器渲染的是单个页面,不经过应用的启动流程。用它验证"布局在不同宽度下会不会崩",是可靠的;用它验证"装到平板上能不能起来",不可靠。

分清楚这两种用途,能省掉很多误判。

在 CodeArts Agent 里改配置是什么体验

module.json5 这个文件,我是在 CodeArts Agent 里改的。

装好官方插件之后,这个文件有 schema 校验——字段名写错、取值不在枚举里,编辑器会立刻标红,不用等构建。我截图那张就是它打开时的样子,deviceTypes 的四行一眼能看到。

这个体验跟"改完再去构建,看报错"完全是两回事。鸿蒙的配置层级多(应用级 app.json5、模块级 module.json5、产品级 build-profile.json5),字段名又长得像,写错层级不一定会报错,但行为会变得莫名其妙。有 schema 拦一道,至少"字段名和取值"这一层的错误不用等到运行时。

代价是它会给你一种"我改对了"的错觉。schema 只管格式,不管语义——deviceTypes 里加个 2in1 完全合法,但你的布局在 2in1 上歪不歪,schema 不知道。

所以我的做法是:schema 负责第一道,预览器负责第二道,模拟器负责第三道。三道都过才算真的对。这次我只过到第二道。

开源之前,先问三个问题

跨端做到能用之后,我开始考虑把这个工程开源出去。理由很简单:它小、干净、有完整的构建脚本,适合当别人的起手模板。

但在按下 git init 之前,我问了自己三个问题。

第一,仓库里有没有不该公开的东西? 证书、密码、本地路径、设备序列号,这些都是。鸿蒙工程里最容易忽略的是 local.properties,它会记录本机的 SDK 路径。

第二,别人拿到能不能跑起来? 如果 README 只写"运行即可",那就是把别人推进同一个坑里。SDK 版本、构建命令、签名前置条件,三样缺一不可。

第三,我愿不愿意维护它? 开源不是发出去就完了。别人提 issue 问"为什么我编译不过",你得回。如果没这个打算,不如只在自己的博客里贴代码。

三个问题的答案都是"能",我才开始动。

.gitignore:逐行解释

我的 .gitignore 只有五行:

/oh_modules
/build
/.hvigor
/.idea
/local.properties

每一行都对应一个具体的坑。

/oh_modules 是依赖目录,等价于 node_modules。它由 ohpm 安装生成,体积大、可重建,绝对不能提交。

/build 是构建产物。我这次所有 HAP 都在 entry/build/default/outputs/ 下面,包括 124 KB 的包和一堆中间文件。提交它除了让仓库变大,没有任何好处。

/.hvigor 是构建缓存,里面存着 project-config.json(记录了 SDK 路径)和任务缓存。它跟本机环境绑定,换台机器就失效。

/.idea 是 DevEco 的工程配置,里面有运行配置、索引缓存,还有你的文件打开历史。

/local.properties 是本地 SDK 路径。

写完之后我验证了一遍,看产物和依赖有没有真的被排除:

在这里插入图片描述

脚本是这样跑的:

git init
git add -A
git ls-files | grep -qE "^(build|oh_modules|\.hvigor)/" && echo "还在索引里" || echo "已忽略"

输出是 已忽略。这一步很值得做,因为 .gitignore 的语法容易写错——少一个斜杠,匹配范围就变了;加了 / 前缀,只匹配根目录。肉眼看不出来,得用 git ls-files 对一遍。

一个真实的教训:预览产物也被提交了

第一次提交之后,我看了一眼文件列表,发现多了一个不该在的东西:

entry/.preview/PreviewBuildParam.json

这是 DevEco 预览器的中间产物。我之前点开预览器时它自动生成的,.gitignore 里没写,就被 git add -A 收进去了。

它本身没什么敏感信息,但这类文件的问题是"每台机器都不一样",提交进去会让别人每次构建都产生 diff,噪音很大。

补一行就好了:

entry/.preview

这件事让我意识到:.gitignore 不是写完就完的,得在第一次提交后回头看一遍清单。因为你不点预览器、不跑测试,根本不知道会有哪些中间文件冒出来。

README 应该写什么

我的 README 很短,四块内容:

在这里插入图片描述

第一块是环境。 写清楚 DevEco 版本和 SDK API 级别。我写的是:DevEco Studio 26.0.0(SDK API 26)。别人一看就知道要装哪套,不用猜。

第二块是构建。 给出具体命令,而不是"用 IDE 构建"。我写的是 bash build.sh,并在注释里说明这个脚本用的是 DevEco 自带的 node 与 hvigor。这一点很关键——我前面就是因为 NODE_HOME 没设,被 hvigor 的报错误导了半小时。

第三块是运行。 明写"需要在 DevEco 里用华为账号自动签名"和"hdc list targets 应能看到一台模拟器或真机"。这是诚实声明,避免别人以为 clone 下来就能跑。

第四块是说明。 一句话讲这个工程是干什么的:验证 CodeArts Agent 与 DevEco 的协作链路。

我见过很多鸿蒙项目的 README 只有一行标题。那不算 README,那算占位符。开源的门槛不在代码,在"别人能不能跑起来",而这件事 90% 靠 README。

提交与推送

本地提交很简单:

git add -A
git commit -m "feat: 最小鸿蒙工程(build.sh + tasks.json + README)"
git log --oneline
15c5820 feat: 最小鸿蒙工程(build.sh + tasks.json + README)

提交信息我习惯写"做了什么 + 为什么",而不是"改了文件"。这条习惯在协作里很值钱——半年后回来看,你只记得提交信息,不记得 diff。

这条工程我第一条提交是 feat: 最小鸿蒙工程(build.sh + tasks.json + README),把三个关键文件都点了名。后面如果补 .gitignore,我会写 fix: 忽略预览器中间产物 .preview,而不是 update .gitignore。区别在于:前者告诉后来的人"为什么要改",后者只告诉他"改了什么"——而 diff 本来就能看出改了什么。

小团队里这条习惯经常被忽略,理由是"就两个人,说什么都懂"。但等第三个人进来,他看的就是提交历史。写得清楚,他不用问人;写得含糊,他得把每个 diff 点开看一遍。

推送到 AtomGit 的步骤和 GitHub 差不多:先在网页上建一个空仓库,拿到仓库地址,然后:

git remote add origin <仓库地址>
git push -u origin main

有两个地方要注意。一是 AtomGit 可能要求配置 SSH key 或者访问令牌,直接 push 会提示认证失败;二是默认分支名,本地可能是 master,平台可能默认 main,不一致时推送会变成新建分支。

我没法在这篇文章里给出确切的 AtomGit 界面步骤,因为我没有账号,也不希望凭印象写错。但流程本身是标准的 Git 流程,这部分照着做不会出问题。

还有一份该带上的东西:构建脚本

开源的时候我把 build.sh 一起提交了。理由很实在:README 里写一堆命令,不如给一个能直接跑的脚本。

#!/bin/bash
DEVECO="/Applications/DevEco-Studio.app/Contents"
export NODE_HOME="$DEVECO/tools/node"
export DEVECO_SDK_HOME="$DEVECO/sdk"
cd "$(dirname "$0")"
"$DEVECO/tools/hvigor/bin/hvigorw" --mode module \
  -p product=default -p module=entry@default -p buildMode=debug \
  assembleHap --no-daemon

脚本里写死了 macOS 上 DevEco 的默认路径,这不算通用。但配合 README 里的一句"如果你的 DevEco 装在别处,改第一行",就够用了。

真正的可移植方案是读环境变量、找不到再回退到默认路径。我没做那么复杂,因为这是示例工程,不是脚手架。

许可证和协作规范,别等别人来问

仓库公开之后,最先被问的往往不是代码,是"我能用吗"。

所以许可证要早放。鸿蒙生态里常见的是 Apache-2.0 和 MIT,两者都允许商用和修改,区别在于 Apache 多了专利授权条款,MIT 更宽松。我这个示例工程用了 MIT,因为它没什么专利价值,越简单越好。

放的位置是仓库根目录,文件名 LICENSE,全大写。别只在 README 里写一句"MIT 协议"——法律上认的是那个文件。

除了许可证,还有两个文件值得加。

一个是 CONTRIBUTING.md。 哪怕只有三行,也要说清楚:提 issue 请附上 SDK 版本和复现步骤,提 PR 请先开 issue 讨论。不写的话,你会收到一堆"编译不过"但没有任何上下文的 issue,回起来很累。

一个是 .editorconfig。 统一缩进和换行符。跨平台协作时,Windows 的 CRLF 和 macOS 的 LF 混在一起,diff 会变得很难看。这个文件两分钟能写好,能省掉很多无意义的格式争论。

这些都是"工程规范"的一部分,跟代码质量无关,但直接决定别人愿不愿意参与。

为什么我没有继续做跨端

写到这里得交代一句:跨端这件事我开了个头就停了。

原因有三个,都很现实。

没有设备。 我只有一台手机形态的模拟器。平板、2in1、手表都没有实例。没有设备就没有真实验证,改出来的东西只能靠猜。

没有优先级。 这个工程是验证链路的样本,不是产品。手机端能跑通,目的就达到了。为了"看起来支持四个形态"去写一堆没验证的代码,反而降低了它的可信度。

适配的收益不在这个阶段。 跨端真正的成本在细节:安全区、折叠屏、分屏、键鼠焦点。这些都要具体设备具体调。现在做,等于提前负债。

所以我停在了"声明支持、布局做了弹性、但只验证手机"这个状态,并且在 README 里写明白了。这是我目前能给出的最诚实的交代。

如果哪天要往下走,顺序应该是:先拿一台平板,把布局在真实尺寸上调一遍;再拿 2in1,试窗口缩放;最后才考虑手表——因为手表的交互模型跟其他三个完全不同,基本等于重写一遍页面。

别人打开你的仓库,第一眼看到什么

这一点我花了点时间想。

仓库首页会显示文件列表。如果第一屏全是 oh_modules、build、.hvigor 这类目录,别人的第一反应是"这仓库没收拾"。如果第一屏是 README.md、LICENSE、.gitignore、build.sh、AppScope/、entry/,观感完全不同。

我提交之后的清单是这样:

.gitignore
.vscode/tasks.json
AppScope/app.json5
AppScope/resources/...
README.md
build-profile.json5
build.sh
code-linter.json5
entry/.preview/PreviewBuildParam.json   ← 这个不该在
entry/...

除了那个漏网的预览产物,其余都还算整齐。把 .gitignore、README、LICENSE 放在根目录,是开源仓库的"门面三件套",缺一件都会显得不专业。

还有一个细节:.vscode/tasks.json 要不要提交?我提交了,因为它定义了"怎么构建",属于工程的一部分。但 .vscode/settings.json 我建议不提交——那里面往往是个人的编辑器偏好,比如字体大小、格式化开关。前者是约定,后者是私事。

这条界线不太好划,我的判断标准是:换个人 clone 下来,这个文件会不会让他必须改? 会,就别提交;不会,提交了反而方便。

开源不是发出去,是接住

写完这些检查项,我对"开源"这件事的看法变了一点。

以前我以为开源的门槛在代码质量——写得够好才配公开。现在觉得门槛在"接住":别人来了,提了问题,你能不能回;提了 PR,你能不能审;跑不起来,你能不能说清为什么。

一个乱七八糟但有人维护的仓库,比一个写得很漂亮但三个月没人管的仓库有用得多。前者至少能让人少走两步弯路。

这也是我最后决定把工程留在这个状态的原因:它不完整,但我知道每处不完整的原因,也能说清楚。如果哪天有人问"为什么手表不支持",我有答案,而不是"还没做"三个字。

复盘:开源前的六条检查

第一,git ls-files 过一遍。 别看目录,看索引。.gitignore 写错了目录里看着干净,索引里可能还有。

第二,证书和密码不进仓库。 这条没有例外。.p12、.p7b、带密码的 build-profile.json5,都不能提交。

第三,中间产物补进 .gitignore。 .preview、build、.hvigor、.idea,这四个最容易漏。

第四,README 写清 SDK 版本。 鸿蒙的版本差异很大,API 12 和 API 26 的工程互相打不开。

第五,写清签名前置条件。 别人 clone 下来跑不通,最先怀疑的就是签名。

第六,给一个能跑的命令。 脚本或者一行命令都行,别让人对着 README 自己拼。

一点补充:为什么没写"元服务"

按最早的想法,我本来想在这篇里加一段元服务(Atomic Service)的落地实践。后来放弃了,原因跟跨端停下的理由一样:我手上没有可验证的环境。

元服务的工程结构和普通应用不完全一样,涉及 ASCF 的配置与构建形态,包体积和冷启动的约束也更紧。这些我可以凭资料写出流程,但写不出"我试过、结果如何"。而这篇里的其他内容,我都自己跑过一遍。

所以宁可空着,也不凑数。如果后面真做了,我会单独写一篇,带上真实的包体积对比和启动日志。

最后

这一篇没什么技术深度,都是收尾的琐事。但收尾恰恰是决定一个工程能不能被别人用起来的部分。

我那个工程现在的状态是:手机模拟器能跑,平板和 2in1 只改了布局没验证,手表没设备因此没做,签名没配所以只能本地跑,仓库整理好了但还没推。

听起来像个半成品,但它每一处的"没做"我都知道原因。这比"看起来都做了、实际哪里都不牢"要好。

如果你也在收拾自己的鸿蒙工程,建议先做两件事:把 .gitignore 写对并验证一遍,把 README 写成"别人照着能跑"。这两件花不了两小时,但能决定你的工程是"一个人的实验"还是"别人能接手的项目"。

我给自己列的下一步是四条,按优先级排:

  1. 把 entry/.preview 补进 .gitignore,然后重做一次提交,让历史干净一点;
  2. 拿一台平板模拟器,把布局真的调一遍,把"只验证手机"这句话从 README 里删掉;
  3. 在 DevEco 里走一次自动签名,把签名步骤写进 README 和 build.sh 的注释;
  4. 把仓库推到 AtomGit,拿到地址,再把地址填回 README 开头。

四条里前两条是技术活,后两条是流程活。都不难,但都需要专门坐下来做——这也说明了收尾为什么总被拖:它不产生新功能,只产生"可交付"。

最后说一句题外的。这一整套事情做下来,我最大的感受不是"鸿蒙难"或者"跨端麻烦",而是一个项目的完成度,取决于你愿意处理多少不体面的细节。.gitignore 少一行、README 少一句签名说明、deviceTypes 多写一个不支持的形态,这些都不影响你自己跑,但都会在别人手里变成坑。

把它们一个个填掉,项目才算真的立起来。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐