用 CodeArts Agent 做跨端改造和开源收尾:deviceTypes、.gitignore 和 README
起因
工程跑通之后,我盯着 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 写成"别人照着能跑"。这两件花不了两小时,但能决定你的工程是"一个人的实验"还是"别人能接手的项目"。
我给自己列的下一步是四条,按优先级排:
- 把
entry/.preview补进.gitignore,然后重做一次提交,让历史干净一点; - 拿一台平板模拟器,把布局真的调一遍,把"只验证手机"这句话从 README 里删掉;
- 在 DevEco 里走一次自动签名,把签名步骤写进 README 和
build.sh的注释; - 把仓库推到 AtomGit,拿到地址,再把地址填回 README 开头。
四条里前两条是技术活,后两条是流程活。都不难,但都需要专门坐下来做——这也说明了收尾为什么总被拖:它不产生新功能,只产生"可交付"。
最后说一句题外的。这一整套事情做下来,我最大的感受不是"鸿蒙难"或者"跨端麻烦",而是一个项目的完成度,取决于你愿意处理多少不体面的细节。.gitignore 少一行、README 少一句签名说明、deviceTypes 多写一个不支持的形态,这些都不影响你自己跑,但都会在别人手里变成坑。
把它们一个个填掉,项目才算真的立起来。
更多推荐



所有评论(0)