用仓颉语言 cj-tauri 框架,五分钟给娃做了个鸿蒙形近字游戏

作者:特立独行的猫A日期:2026/11/15

女儿十岁,五年级了,经检查有多动症ADHD 加阅读障碍,注意力很难长时间挂在一件事上。医生说要多做辨字训练,我就想做个小游戏:把小学一到五年级那些长得像的汉字凑成一组,让她在一堆"长得很像"的字里找出不一样的那个。用一个周末,给十岁的女儿做了个形近字游戏(使用仓颉语言的 cj-tauri 跨段端开发框架)。

方案是我自己先写了一份文档:五个玩法、字库分级、奖励机制都列好了。真正难的从来不是设计,是把它变成能跑的东西——尤其当它得先在电脑上跑,之后还要挪到鸿蒙平板上。这就是cj-tauri赞的地方:同一套源码,换个构建方式就可以支持鸿蒙PC啦。开发起来先在电脑上跑,再跑到设备上一样的效果。

这篇就记这一路:选了什么框架、栽在哪三个坑里、最后怎么连cj-tauri上游框架的 bug 一起修了并顺带给cj-tauri提了个pr。


一、选型:为什么是 cj-tauri

方案文档里原本写的是 Vue 3 + Phaser + localStorage,纯 H5。但我想让它在平板上是个真应用,不是浏览器里的一个页面——孩子会自己切走,家长还得开"引导式访问"锁屏,太折腾。

cj-tauri 的形态正好:仓颉后端 + 系统 WebView 前端,仓颉静态编译出一个 exe,前端还是我熟悉的 HTML/CSS/JS。更关键的是它一份业务代码可以同时出桌面和鸿蒙两个产物——现在先跑windows电脑桌面,等鸿蒙平板接上,重新编一次就行在平板上了。

1hanzi-game/
2├── cj-tauri.toml          # 唯一真相:应用 id / 窗口 / 页面入口 / 能力目录
3├── src/                   # 仓颉后端(存档命令)
4├── assets/ui/             # 前端:index.src.html + css/ + js/
5└── tools/build-ui.js      # 前端内联器(后面会讲为什么必须有它)
6

二、第一版就栽了:页面起来了,但零样式零脚本

按 skill 的说法,"页面超过一屏就独立成 assets/ui/index.html",我就老老实实拆成了 index.html + css/style.css + js/app.js 七八个文件,页面里正常写相对引用:

1<link rel="stylesheet" href="css/style.css">
2<script src="js/app.js"></script>
3

编译通过,窗口也起来了。然后我看到的是这个:

字都在,但完全没有样式——原本用 display:none 藏起来的五个页面(首页、游戏页、结算页、图鉴、家长中心)全部摊在一屏上。而且桥日志里一行错误都没有:

1[cj-bridge] controller ready, loading page
2[cj-bridge] NavigateToString -> hr=0x00000000      ← 看着完全正常
3[cj-bridge] html navigation requested
4

我一开始以为是自己 CSS 写错了,改了两轮才反应过来:JS 也没执行——首页的年级列表、玩法卡片应该是由 JS 渲染的,全是空的。也就是说整个 js/ 目录一个文件都没加载。

翻框架源码才明白:PageSource.Asset 是"把 HTML 文件读成字符串",Windows 侧再走 NavigateToString——文档没有真实来源,相对路径的 <link href> / <script src> 一律解析不到。

判定方法我后来写进了踩坑记录:NavigateToString -> hr=0x0 是"成功"行,别被骗;真正的判据是页面自检行出不来。

1// 页面启动成功后回投一行到仓颉 stderr
2bridge.invoke('report', { line: 'boot ok · bridged=' + bridged + ' · groups=' + groups });
3

日志里出现 [frontend] boot ok · bridged=true · groups=102,才算页面真的活着。

解法:源码分文件,构建时内联成一个自包含页面

我不愿意为了这个把 CSS/JS 全塞进一个一万行的 HTML 里——那没法维护。所以加了一个 30 行的内联器:源码仍然是分文件的,跑一下 node tools/build-ui.js 生成自包含的 index.html。

1// tools/build-ui.js 的核心就两条正则
2html = html.replace(/[ \t]*<link\b[^>]*href="([^"]+)"[^>]*>/gi,
3  (m, href) => '<style>\n' + readAsset(href) + '\n</style>');
4
5html = html.replace(/[ \t]*<script\b[^>]*src="([^"]+)"[^>]*><\/script>/gi,
6  (m, src) => '<script>\n' + readAsset(src) + '\n</script>');
7
8// 内联完还有相对引用就当场失败,别让下一次运行再当侦探
9const leftover = html.match(/(?:src|href)="(?!https?:|data:|#)[^"]+"/g);
10if (leftover) process.exit(1);
11

生成的是 110 KB 的单文件页面。同一份代码,跑起来是这样:

这一坑后来提成上游 issue #9:框架内部其实知道这个限制(AGENTS.md 提过一句),但面向使用者的 skill 和模板都没说,照做就必然踩。我在 issue 里建议了三步——check 扫到相对引用就告警、skill 补一句、将来用 SetVirtualHostNameToFolderMapping 真支持。


三、游戏本体:一局 5 题,五种玩法

字库我按方案文档整理成 102 组,覆盖一到五年级(13/14/22/31/22 组),每组带拼音、词组、偏旁和一句记忆口诀:

1['点画系列', '大下加点是太,大右加点是犬',
2  [['大', 'dà', '大小', '大'], ['太', 'tài', '太阳', '大'], ['犬', 'quǎn', '警犬', '犬']]],
3

数据结构是紧凑的一行一组,改字库不用碰仓颉代码,改完 node tools/build-ui.js 就生效(我写了个校验脚本,确认 102 组里每个词组都真的含那个字)。

五种玩法

玩法练什么怎么玩
?? 火眼金睛整体字形辨识一堆相同的字里找出不一样的那个(或者找出和样例一样的)
?? 汉字配对字 ? 词义左栏字、右栏词语,点着连起来
??? 偏旁侦探偏旁归因给一个字,从偏旁里挑出它的偏旁
?? 听音辨字听觉 → 视觉听读音选字,读不出来就退化成看拼音选
?? 组词挑战语义理解词语挖个空,选能填进去的字

难度是自适应的:连对就多一个干扰项(最多 6 个选项),答错就退一格。答错也不惩罚——不给星,但也不扣星;同一题错到第 3 次,自动把记忆口诀显示出来:

口诀:日里一横是太阳,目里两横是眼睛

奖励与家长端

星星一颗一颗攒,攒够就喂宠物升级(6 个形态,从蛋宝宝到汉字神龙)。徽章 7 枚,最早解锁的那个是"初出茅庐——完成第 1 局",答对 0 题也给你:

注意那句鼓励语——"今天这几个字有点难,你都坚持做完了,明天再来一次就会更熟"。夸过程不夸结果是方案的硬要求,代码里所有文案都按这条写,答错时说"再看看这两个字差在哪",绝不出现"错了""笨"。

家长中心单独设了密码(默认 1234),进去能看到今日时长、正确率趋势,以及反复答错的字组自动进"重点复习区":

折线图是我自己用 Canvas 画的,没引第三方库——一个 chart.js 加进来就要考虑离线包体积,不值得。


四、仓颉后端只干一件事:把进度存下来

前端用 localStorage 也能存,但那东西在 WebView 里不保险(那些页面没有真实来源,origin 是 opaque,某些情况下直接抛 SecurityError)。孩子的星星和徽章不能丢,所以我让仓颉侧写文件。

四条命令,都在 src/storage.cj 里:

1progress:load   读存档(返回 JSON 文本,空存档回空串)
2progress:save   覆盖写(入参 { data: "<JSON 文本>" })
3progress:path   回存档路径(家长备份用)
4app:about       版本与数据目录
5

cj-tauri 有个"三处联动"的铁律,漏一处前端就用不了:

1// ① 实现 + 注册
2public func build(): AppSpec {
3    return AppSpec()
4        .window(WindowConfig("形近字辨别训练", 1024, 720))
5        .wire({ app =>
6            app.register("progress:load", ProgressLoadCommand())
7            app.register("progress:save", ProgressSaveCommand())
8            // ...
9        })
10}
11
1// ② assets/capabilities/default.json 里放行(否则前端拿到 command not allowed)
2{ "commands": ["progress:load", "progress:save", "progress:path", "app:about", "report"] }
3
1// ③ 前端 invoke
2bridge.invoke('progress:save', { data: JSON.stringify(state) })
3

只做 ①③ 会得到 command not allowed,只做 ①② 会得到 command not registered。我第一次就漏了清单,报错信息倒是很清楚。

存档落在 %LOCALAPPDATA%\cj-hanzi-game\progress.json——应用自己的目录,不是项目目录,这样换工作目录启动也不丢进度。写之前先校验一遍 JSON 合不合法,不合法就拒写:"宁可丢一次保存,也不要把存档写坏"。

前端还留了兜底:后端不可用时退回 localStorage,并且每次保存都同时写一份本地缓存。真出问题时至少不是全丢。


五、两个把我卡了半小时的环境坑

这两个都不算框架的锅,但都不给任何提示,值得记下来。

坑 A:cjpm 在完整 PATH 下静默退出 127

1$ cjpm -v
2$ echo $?
3127
4

一个字符都不打。查了半天才发现是 PATH 顺序:把仓颉的 bin、tools/bin、runtime/lib/windows_x86_64_cjnative 放到 PATH 最前面就好了。同样的二进制,同样的参数,顺序不一样结果就不一样——这种问题没有任何报错,只能靠对照实验。

坑 B:少了 WebView2Loader.dll,窗口一闪而过

编译一切正常,双击产物,桥只打一行就销毁窗口:

1[cj-bridge] host thread started
2[cj-bridge] WebView2Loader.dll not found: put it next to the exe or on PATH
3[cj-bridge] host destroyed: 000001575fcd8780
4

而 cj-tauri info 会告诉你 C 桥已构建、cjc/stdx/cjpm 全部解析正常——info 全绿不代表能跑。把框架 native/webview2/WebView2Loader.dll 拷到 exe 旁边就完事。

这两条我都提进了上游 issue #11,顺带还报了两个:cj-tauri check 的三方比对失败时只回十进制 code=3221225781(我是自己换算成 0xC0000135 才认出是 DLL 未找到),以及 cj-tauri create --help 会把 --help 当项目名建出一个目录。


六、顺手把上游的一个 bug 修了

做这个游戏的过程中我跑了 cj-tauri check,它说:

1[cj-tauri] 骨架漂移:targets/desktop/cjpm.toml 与生成器输出不一致(运行 cj-tauri sync desktop 重新生成)
2

行,我按提示重跑 sync,再 check——还是这条。再 sync,再 check,还是。这就不是"我改坏了",是它自相矛盾。

翻了 cli/src/sync.cj 才看明白,是三个小问题叠在一起:

  1. 读业务包 cjpm.toml 里 path = "E:\\test\\a" 时没做 TOML 反转义,\\ 原样带下去,最后渲染成 E://test//a 写进我的 targets/;
  2. sync 用业务包声明渲染,check 却用 resolveFrameworkRoot() 重新渲染再比字符串——两条来源形式不同,比对永远不成立;
  3. toTomlPath 只把 \ 换成 /,不合并重复分隔符,所以老骨架里那个 E:// 永远比不相等。

修法也就三行思路:还原转义、两处共用一个取根入口、比对时两侧都归一化。

1// 唯一入口:sync 与 check 都必须走它,否则就等着"sync 完立刻报漂移"
2func resolveSkeletonFrameworkRoot(verbose: Bool): Option<String> {
3    match (readBizFrameworkPath()) {
4        case Some(p) =>
5            if (verbose) { eprintln("[cj-tauri] 框架路径取自业务包声明:${p}") }
6            return Some(p)
7        case None => return resolveFrameworkRoot()
8    }
9}
10
1// 归一化时保留开头的 UNC `//`:那是 Windows 共享路径,不能合并掉
2func toTomlPath(p: String): String {
3    let s = p.replace("\\", "/")
4    // ... 合并重复分隔符 ...
5}
6

我还补了 5 条回归测试,守两条不变量:TOML 转义必须还原(未知转义不许被吃掉)、分隔符必须合并且幂等。

验证时我特意做了个 A/B

cd cli && cjpm test 跑出来 10 条里 2 条红。我第一反应是"我改坏了",但没敢直接改测试——先把我的改动 stash 掉,在基提交上重跑:

1基提交(无我的改动):TOTAL 5,PASSED 3,FAILED 2   ← 同样这两条
2带上我的改动:       TOTAL 10,PASSED 8,FAILED 2   ← 新增 5 条全过,红的还是那两条
3

结论清楚了:那两条 [links] 用例在基提交上就是红的,不是我引入的。测试红了先做对照实验,别急着改测试让它变绿——那是掩盖问题,不是修问题。

修复提成了 PR #25,文档沉淀(速查表 4 条 + AGENTS.md §4 三条)提成了 PR #24。

顺带还有个没修的:scripts/test.sh 在我这机器上链接期失败,libstdx.crypto.x509.a 缺 CertOpenSystemStoreA 一类的符号(mingw 的 link-option 少了 -lcrypt32,基提交就这样)。这条我如实写进了 PR 说明,没顺手夹带——一个 PR 只做一件事,不然 review 的人会很难受。


七、上鸿蒙平板:装包三十秒

桌面跑通只是半场。平板接上那天,真正的门槛是签名——鸿蒙真机不认自签,它只信「包名 + 设备 UDID」双匹配的 profile。

我一开始先跑离线体检:

1[sign] 包名: com.example.hanzi_game
2[sign] 设备 UDID: (取不到)
3[sign] 原因: 拿不到设备 UDID(设备没连?跑 `hdc shell bm get --udid` 看看)
4

设备明明连着。真相是 hdc 不在 PATH 里(它躺在 DevEco 的 toolchains 目录下)。把这个目录加进 PATH,同一条命令立刻改口:

1[sign] 设备 UDID: 667BA4F7…DCE1443
2[sign] 原因: 本机没有「含本机 UDID 且包名为 com.example.hanzi_game」的材料
3[sign] 下一步: 跑 `cj-tauri sign --login` + `sign --auto` 为这个包名现签一份
4

这条我也拿去提了上游(见文末),因为它给出的第一句结论会把人往「是不是线坏了」的方向带。

按提示走自签名:sign --login 弹一次浏览器、登录 AGC(令牌加密落盘、约 4 小时有效),sign --auto --newKeys 本地现生成密钥对——私钥永不上云,只把 CSR 交上去换证书,再把 profile 和密文口令写回 build-profile.json5。整套一分钟,cj-tauri的自签名,比在 DevEco 里点自动化流程还快。

然后我踩了个顺序坑

改完样式重新生成页面后,我按习惯跑了 cj-tauri sync ohos —— 它把 build-profile.json5 按模板重写了一遍,signingConfigs 变回空数组。接着打包:

1> hvigor Finished :entry:default@SignHap... after 2 ms          ← 快得可疑
2[ohos] HAP = …/entry-default-unsigned.hap
3[ohos] 注意:这是未签名包,不能装进设备。
4

再跑一次 sign --auto(不带 --newKeys,想复用已有材料)时,它到第 ⑥ 步就结束了,没打印第 ⑦ 步「已写回 signingConfigs」、也没报错——因为那份 p12 的口令是上一次随机生成、只在当时存在过,写回需要的密文它拼不出来,于是静默跳过。于是你会拿着一个「签名成功过」的工程,编出未签名的包。

落法很简单,但得知道:顺序是 sync → sign → build,签完不要再 sync;真要重来就 sign --auto --newKeys,它会把口令重新生成一遍并写回。

装上去之后,一次就成了:

1hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
2hdc shell aa start -a EntryAbility -b com.example.hanzi_game
3

鸿蒙真机上的样子

同一份 assets/ui/,在 1840×2800 的平板竖屏上(SLG-W10):

第一次装上去(上图是调过之后的)我看着别扭:.big-btn { margin-top: auto } 在 2800px 高的屏上把「开始练习」顶到了屏幕最底,中间空出一大片,像布局没写完。于是加了一段针对高窗口的媒体查询——内容成组居中、字号整体放大、字卡和选项卡也跟着放大(孩子不用凑近屏幕):

1@media (min-height: 900px) {
2  #view-home { justify-content: center; }
3  #view-home .big-btn { margin-top: 22px; }
4  .home-title { font-size: 40px; }
5  .target-char { font-size: 176px; }
6  .opt-card .opt-char { font-size: 104px; }
7}
8

游戏页在鸿蒙平板上:

到这里,一份业务代码,桌面和鸿蒙两端都跑起来了——src/ 里那 200 行仓颉、assets/ui/ 里那 10 个前端文件,两端共用的就是同一份,差别只在 cj-tauri.toml 派生出两个骨架。

八、现在它能干什么,以及下一步

已验证的(都有实机截图和桥日志对应):

  • 五种玩法都能玩,作答判定、进度点、连击、鼓励气泡都对;
  • 一局 5 题走完会进结算页,星星计入存档、徽章解锁;
  • 家长中心的密码门、统计、折线图、重点复习区都正常;
  • 存档经仓颉命令落盘,文件内容我核对过;
  • 鸿蒙平板实机跑通:签名、装机、启动、1840×2800 竖屏布局都验过。

没验证的也得说清楚:

  • 音效和语音朗读——Web Audio 合成 + SpeechSynthesis,桌面和平板都只验证了不抛错、不阻塞玩法,好不好听得孩子耳朵说了算;
  • 平板上的长时间使用(半小时以上会不会内存涨、ArkWeb 会不会掉帧)没测。

下一步就是等她放学试玩,然后接平板:

1export CANGJIE_STDX_OHOS=<鸿蒙版 stdx>/linux_ohos_aarch64_cjnative/dynamic/stdx
2cd targets/ohos && npx cj-tauri build
3cd targets/ohos && npx cj-tauri run --install     # 先 cj-tauri sign 检查签名材料
4

对她来说,这个游戏是不是用仓颉写的、有没有踩坑、上游修了几个 bug,全都不重要。她只关心一件事:自己选的宠物今天长大了没有。


链接汇总


参考文档


《用仓颉语言 cj-tauri 框架,五分钟给娃做了个鸿蒙形近字游戏》 是转载文章,点击查看原文。


相关推荐


JWT 不是登录方案:三种登录态架构怎么选
深蓝AI2026/11/6

最近讨论 JWT 时,经常会出现两种相反的结论:一种认为 JWT 天然比 Session 更现代,另一种认为成熟网站都不该用 JWT。把这两个结论放在一起看,问题其实不在 JWT 本身,而在于大家把三个不同层次的东西放进了同一场比较。 Session 解决的是服务端如何保存登录状态;JWT 是一种携带声明的令牌格式;Opaque Token 则强调令牌内容对持有方不可见,资源服务器需要向授权服务查询状态。它们可以出现在同一个系统里,也可以组合使用,并不是三种互斥的登录技术。 真正决定方案的,不是


GitHub 热榜项目 - 周榜(2026-10-26)
CoderJia_2026/10/29

GitHub 热榜项目 - 周榜(2026-10-26) 生成于:2026-10-26 统计摘要 共发现热门项目: 15 个 Token赞助:siliconflow 前些天发现了一个巨牛的人工智能学习网站,通俗易懂,风趣幽默,忍不住分享一下给大家。点击跳转到网站。 本期热点趋势总结 从本期 15 个项目看,AI 编程工具的配套能力依然是一个集中方向:opencode 提供开源编码代理,Orca 和 T3 Code 关注代理的操作与管理,ruflo 则探索多


数据库如何通过 MVCC 实现隔离性
tryxr2026/10/21

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */ #content_views .toc, /* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */ #content_views.markdown_views > p:empty:has(+ .toc), #content_views.markdown_views > .toc + p:emp


k3s + Cilium + Tailscale 双栈网络改造:评估、实验与生产落地
东风微鸣2026/10/17

前言 终于等来了国庆长假!宅在家折腾自己的 HomeLab、 K8s、 NAS 服务器集群的感觉真爽!这次长假真的是折腾了好多东西,感兴趣的读者请期待后续的爆更,等不及的话也可以直接看我的 repo - east4ming/homelab2 的 PR 和 Commits。 这应该是2026国庆系列的最后一篇了。 起因很朴素:家里那套 homelab k3s 集群跑了两年多,一直是 IPv4-only。运营商给了 /56 的 IPv6 前缀,路由器上静态路由也配好了,集群内部就是不动。每次从


Linux网络学习【⽹络基础概念】
承渊政道2026/10/11

🔥承渊政道:个人主页 ❄️个人专栏: 《C语言基础语法知识》 《数据结构与算法》 《C++知识内容》 《Linux系统与网络知识》 《算法刷题指南》 《测评文章活动推广》 《大模型语言路线学习》 《MySQL数据库学习》 《Python知识内容》 《cpolar知识学习》 ✨逆境不吐心中苦,顺境不忘来时路!✨ 🎬 博主简介: 在Linux系统学习中,网络基础是系统编程、网络编程以及服务器开发必须掌握的一块核心知识.很多看似简单的操作,例如访


【C++进阶】哈希表实现
重生之小比特2026/10/3

目录 一、哈希核心概念 1.1 直接定址法 1.2 哈希冲突(哈希碰撞) 1.3 负载因子 load‑factor 1.4 关键字转为整数 二、常见哈希函数 2.1 除留余数法(除法散列法,工程最常用) 2.2 乘法散列法(了解,极少手写) 2.3 全域散列法(了解,对抗恶意哈希攻击) 2.4 字符串哈希 BKDR(面试手写高频) 三、冲突两大解决方案 方案一:开放定址法(Open Addressing) ⚠开放定址法删除的致命问题 开放定址完整代码(线性探测版本


Claude注册,订阅,防风,解风经验!
甲维斯2026/9/27

好像很多人关心 Claude 账号的问题,我就专门写一篇! 现在的 Claude 真的非常有“性价比”! 能力绝对顶得不行,价格还比 GPT-6 Astra 便宜。 然后同样 20 美金套餐,差 7~9 倍的 tokens,还没考虑 tokens 效率的问题。 最强模型,最高性价比!很多人都想冲?但是又会遇到一系列问题! 第一个问题:这么好的事儿,如何拥有呢? 第二个问题:如何长期稳定的拥有呢? 第三个问题:万一失去了,如何重新拥有呢? 这几天来,大家问得最多的就是如何稳定使用 Claude。


阿里开源的 AI 代码评审工具,我喂了 5 个坑,一个没漏
Flynt2026/9/19

今天上午刷 GitHub Trending,榜首是阿里开源的 open-code-review,一天涨了三千多星。星数不是重点,重点是它踩中了我最近的一个真实困扰:AI 把写代码的门槛打下来了,review 却还在原地踏步——Cursor、Claude Code 生成的代码越来越多,谁来审? 把 diff 直接丢给通用 AI 聊天框去 review,我试过很多次,结果基本三种:改了 30 个文件它只盯着一处喷;报的问题行号对不上;再来一堆"建议增加注释"式的正确废话。token 倒是烧得很爽。


从 “什么是 MySQL“ 到库与表的完整操作(MySQL基础篇)
bksczm2026/9/10

在学 MySQL 时,我们常说: mysql 是客户端,mysqld 是服务端; 创建数据库后,/var/lib/mysql 下就多了一个文件夹; 备份就是用 mysqldump 把 SQL 语句保存下来,还原就是 source 执行一遍; 存储引擎决定了数据怎么存、怎么索引、怎么锁。 这些话背后藏着几个值得深究的问题: MySQL 的 C/S 架构到底是怎么工作的?存储引擎(InnoDB / MyISAM)到底解决什么问题,为什么说它是 "发动机"?DCL 和事务(


【框架篇】Spring MVC 介绍及使用(详细教程)
2601_962065492026/9/2

Spring MVC 介绍-------------### 1,MVC 设计模式MVC(Model-View-Controller)是一种常见的软件设计模式,用于将应用程序的逻辑分离成三个独立的组件:1. 模型(Model):模型是应用程序的数据和业务逻辑的表示。它负责处理数据的读取、存储和操作,以及业务规则的处理。模型通常是独立于用户界面的,可以在不同的视图和控制器之间共享和重用。2. 视图(View):视图是用户界面的呈现部分,负责展示数据给用户,并接收用户的输入。视图通常是根据模型的数

首页编辑器站点地图

本站内容在 CC BY-SA 4.0 协议下发布

Copyright © 2026 聚合阅读