手表上那个会随心率变色的表盘、跑步时能自动分段的小工具本质上都是跑在佳明设备 Connect IQ 虚拟机上的小程序而写这些程序的官方工具链里Visual Studio Code 已经成了比 Eclipse 更顺手的那条路。这篇文章讲的就是怎么在自己的电脑上把佳明穿戴设备 APP 开发平台搭起来从 Java 运行时、Connect IQ SDK Manager、SDK 版本选择到 VS Code 里的 Monkey C 扩展、开发者密钥、manifest.xml 与 monkey.jungle 的写法再到编译、模拟器联调、真机侧载和打包上架最后是那堆让人抓头的报错怎么按线索倒推。目标读者是手里有一块佳明表、想给自己或朋友写个小工具的人也适合做智能穿戴设备设计方案时需要一个可跑通的验证环境的人。前置知识只需要会装软件、会在命令行敲两条命令Monkey C 这门语言本身可以边写边学。1. 先搞清楚这套工具链里谁在干活很多人第一次搭佳明开发环境时会下意识地把它当成装个 IDE 然后就能写代码的常规流程结果 VS Code 装好了、扩展也装了一编译还是报错因为没弄明白真正干活的是哪个进程。这个认知如果一开始就建立起来后面九成的环境类问题都能自己定位。1.1 Monkey C 不是 C别拿 C 的思路往上套佳明穿戴设备上的应用语言叫Monkey C源文件后缀是.mc。名字里带 C但它跟 C 语言的关系大概只有都能写逻辑这一层。Monkey C 是动态类型的变量声明用var运行时才确定类型它有垃圾回收没有指针没有手动内存管理也不能开线程。写法上更接近 JavaScript 和 Java 的混合体代码被编译成字节码跑在设备固件里的一个虚拟机上。这个差异会直接影响你的编码习惯。举个例子C 里习惯的申请一块缓冲区循环复用在 Monkey C 里通常换成Toybox.Lang.Array或者ByteArrayC 里靠线程解决的耗时任务在 Monkey C 里靠回调和事件循环解决。日常最常用的几个库是Toybox.System时间和系统信息、Toybox.WatchUi界面、Toybox.Graphics画图、Toybox.Sensor传感器、Toybox.Activity当前运动数据、Toybox.Communications和手机端通信、Toybox.Math、Toybox.Time。你可以在 SDK 目录的doc文件夹里找到完整的 API 文档离线可查比在线翻快得多。编译产物有两种.prg是设备上实际运行的包.iq是提交到应用商店的打包格式。两者的关系有点像 APK 和签名后的发布版 APK。1.2 四件套的分工边界整套环境其实由四个互相独立的东西组成搞清楚各自的职责报错时才知道该往哪查。组件形态职责出问题的典型症状Connect IQ SDK Manager一个 Java 桌面程序下载、管理不同版本的 SDK双击没反应、启动就闪退Connect IQ SDK一个目录含命令行工具提供monkeyc编译器、模拟器启动器、设备定义、示例工程提示找不到monkeyc模拟器 Simulator独立进程由 SDK 里的命令拉起在电脑上虚拟一台佳明设备跑你的 prg设备列表里没有目标机型开发者密钥一对.der/.pem文件给编译产物签名设备只认签名过的包编译报签名相关错误注意 SDK 本身不带图形界面它给你的是一堆命令行工具。VS Code 的 Monkey C 扩展做的事情说白了就是帮你把这些命令行参数拼好、把输出显示在面板里。理解这一层意味着任何 VS Code 报错你都能退回到命令行自己复现一遍这是排查环境问题最有效的姿势。1.3 为什么是 VS Code 而不是 Eclipse佳明的 Connect IQ 开发最早主推 Eclipse 插件那个插件到现在还能用但装一次要拖一堆依赖启动慢而且 Eclipse 本身对其他语言的体验一般。VS Code 扩展的好处是轻、启动快、可以同时开好几个项目窗口更重要的是它生成的构建命令是可见的——你在终端里能看到它实际执行了什么。但别把 VS Code 想得太神。它不会帮你下载 SDK不会帮你装 Java很多环境变量还是得自己配。它就是个体面的外壳真正编译你代码的是monkeyc。顺带处理一个高频误解佳明开发不需要在 VS Code 里配 C/C 环境也不需要写c_cpp_properties.json、装 Microsoft 的 C/C 扩展。那套东西是给 STM32、LVGL 模拟器、纯 C 项目用的跟 Monkey C 完全两码事。同理搜索结果里出现的 vscode flutter android 项目报错unable to find suitable visual studio toolchain那是 Flutter 在 Windows 上构建桌面端时找不到 MSVC 工具链找的是 Visual Studio不是 Visual Studio Code跟佳明开发一个字都不沾。2. 环境搭建Java、SDK Manager 与版本选择这一段是全程最容易劝退的地方因为报错往往发生在你还没开始写一行代码之前。我的建议是严格按顺序来每完成一步就验证一次别一口气装完再统一排错那样出问题时变量太多。2.1 Java 运行时的三个细节SDK Manager 是个 Java 程序所以第一步是装 Java 运行环境。三个细节值得注意第一装 64 位版本。32 位的 Java 在现代系统上启动 SDK Manager 可能出现内存不足或者直接闪退而且这个错误信息非常不友好。第二版本别太老也别太新。Java 8 是底线但新版 SDK 和扩展在 Java 11 或 17 上更稳。我自己的做法是装一个 JDK 17而不是只装 JRE——虽然 SDK Manager 本身只需要运行时但多几十兆换来的是遇到奇怪问题时不用再回头补装。第三配好JAVA_HOME。Windows 上在系统环境变量里新建JAVA_HOME值指向 JDK 安装目录不要带\bin然后把%JAVA_HOME%\bin追加到Path里。macOS 和 Linux 上同理写进 shell 的配置文件。配完开一个新的终端验证java -version能打印出版本号就说明通了。如果提示命令不存在先别急着装第二遍多半是终端没重启或者路径写错了比如把bin也塞进JAVA_HOME了。2.2 SDK 的安装路径有讲究从佳明开发者站点下载 SDK Manager跑起来之后它会让你选一个目录来存放 SDK 版本。这里有一条经验路径里不要出现空格、中文和特殊符号。原因不是 SDK 本身有问题而是整个工具链里有一堆脚本、配置文件和命令拼接过程路径带空格时如果某一层忘了加引号就会把路径从中间截断报出来的错误往往是什么找不到文件或者意外的参数查半天查不到根上。这类坑历史上在 Windows 用户里出现得特别多。推荐放在WindowsC:\Garmin\connectiq-sdkmacOS / Linux~/garmin/connectiq-sdkSDK Manager 支持多版本共存每个版本下载下来是独立的一个目录比如connectiq-sdk-win-8.x.x这样。目录结构大致是这样connectiq-sdk-版本/ ├── bin/ # monkeyc、connectiq、模拟器等命令行工具 ├── doc/ # 离线 API 文档 ├── samples/ # 官方示例工程强烈建议通读几个 └── resources/ # 设备定义、字体等资源samples那个目录别跳过。里面有几个完整的表盘和小工具示例是理解manifest.xml和monkey.jungle该怎么写的最快途径比看文档快。2.3 选哪个 SDK 版本从目标设备反推这是最需要动脑的一步。SDK 版本不是越新越好因为SDK 版本决定了你能用哪些 API而设备决定了它最多支持到哪个 API 等级。判断逻辑是这样的先确定你要支持哪些设备。如果你是自己用就是你手上那块表如果要给别人用看用户群里哪几款机型最多。查这些设备各自支持的 Connect IQ 版本在 SDK 的resources或者设备列表里能查到官方文档也有对应表。选一个不低于这些设备支持版本、同时尽量新的 SDK。低了会导致某些 API 用不了高了会导致编译出来的包在老设备上装不上。举个具体的情景你手上有两块表一块是几年前的入门款只支持到较低的 CIQ 版本另一块是近两年的旗舰。这种情况下最稳的做法是下两个 SDK 版本共存主力用新版开发需要兼容老设备时切换 SDK 路径重新编译一次看是否有 API 报错。VS Code 的扩展不同工作区可以配不同的 SDK 路径切换成本很低。这里有个隐藏的坑manifest.xml里有个minApiLevel字段它声明的是这个应用最低要求的 API 等级。如果你在代码里用了某个新 API但minApiLevel设得比它要求的低编译器会直接报符号找不到或者类似的错误。这个报错看起来像是这个类不存在实际是在告诉你你的目标 API 版本里没有这个类。看到这类错误第一反应应该是去查这个 API 是从哪个版本开始提供的而不是怀疑自己拼错了类名。2.4 要不要把 SDK 的 bin 放进 PATH把 SDK 的bin目录加到系统的PATH里好处是终端里可以直接敲monkeyc和connectiq。这个能力在排错时非常值钱当 VS Code 扩展报找不到编译器时你可以立刻开个终端敲一遍monkeyc --version如果这里也报错说明是环境问题如果这里正常说明是扩展的 SDK 路径配置问题。一下就缩小了范围。代价是路径里只能有一个版本多版本共存时PATH里放的应该是最常用的那个。其他版本靠 VS Code 工作区设置里的绝对路径来指定。我自己的习惯是PATH里放主力版本然后每接一个新项目先跑一遍monkeyc --version确认当前生效的是哪个。3. VS Code 这一侧扩展、配置与开发者密钥环境装好之后VS Code 这边其实要做的事情不多但每一件都很关键尤其是开发者密钥这一环新手特别容易忽略。3.1 装 Monkey C 扩展顺便说清中文语言包的事在 VS Code 的扩展面板里搜Monkey C认准发布者是 Garmin 的那个。装完之后你会得到几样东西.mc文件的语法高亮、几组以Monkey C:开头的命令、以及对monkey.jungle和manifest.xml的基本识别。关于把 VS Code 改成中文这事你可以做但要有心理预期中文语言包只翻译 VS Code 自身的界面Monkey C 扩展的命令名和输出日志仍然是英文。也就是说命令面板里你还是得搜Monkey C:构建输出还是英文。所以没必要为了这个纠结反而英文命令名更利于你复制到搜索引擎里查。真要装扩展面板搜Chinese装官方语言包重启后按提示切换即可。常用命令都在命令面板Windows/Linux 是CtrlShiftPmacOS 是CmdShiftP里输入Monkey C会列出一组常见的包括Monkey C: New Project—— 从模板新建工程Monkey C: Generate Developer Key—— 生成开发者密钥Monkey C: Verify Installation—— 检查环境是否完整Monkey C: Build Current Project—— 编译当前工程Monkey C: Build for Device/ 运行类命令 —— 编译并在模拟器里跑起来不同版本的扩展在命令名称上会有一点增减以你装的版本实际列出来的为准。3.2 settings.json 里真正要写的几行配置项在 VS Code 设置里搜monkeyC就能全部列出来。最核心的是这么几项写在工作区级的.vscode/settings.json里好处是跟着项目走换机器不会忘{ monkeyC.sdkPath: C:/Garmin/connectiq-sdk/connectiq-sdk-win-8.x.x, monkeyC.developerKeyPath: C:/Garmin/keys/mykey.der, monkeyC.currentDevice: fr965 }几个细节路径用正斜杠/或者双反斜杠\\单反斜杠在 JSON 里是转义字符会直接把配置写坏。sdkPath指向的是 SDK 的根目录不是bin目录。currentDevice决定默认编译目标填的是设备 id比如fr965、fenix7这种小写形式。这个值必须出现在工程的manifest.xml的products列表里否则编译时会被拦下来。有些版本的扩展会提供设备下拉选择你把currentDevice写对之后状态栏上会显示当前设备。工作区级配置适合团队协作用户级配置适合放在自己机器上做默认值。我一般两边都写用户级放 SDK 路径和密钥路径个人机器固定的东西工作区级放currentDevice和 jungle 路径跟项目相关的东西。3.3 开发者密钥它到底签了什么这一步新手最容易漏漏了之后的表现是编译到一半报签名相关的错误或者模拟器能跑、真机装不上。生成方式有两种效果一样命令面板执行Monkey C: Generate Developer Key按提示选目录、输入名字比如mykey。直接在终端里跑monkeyc -g mykey在-g后面跟文件名。跑完之后目录里会出现两个文件mykey.der和mykey.pem。.der就是要填到monkeyC.developerKeyPath里的那个编译时通过-y参数传给编译器.pem是私钥文件单独找个地方备份好不要放进公开仓库。为什么需要密钥因为佳明设备只运行经过签名的应用包这是设备侧的一道基本校验。这也意味着一旦你用某个密钥签名并上架了应用后续版本最好继续用同一个密钥避免出现身份不一致导致上传被拒的情况。多台电脑开发时把同一对密钥拷过去用不要每次换机器都重新生成。提示.pem文件丢了的后果比.der丢了好一些但两个都建议备份到私有位置。顺手在.gitignore里加上*.pem和*.der这个习惯能省掉很多麻烦。3.4 Verify Installation 这条命令的价值命令面板里有一条Monkey C: Verify Installation很多人装完扩展就直接去新建项目了从来不点它。我建议养成习惯环境搭完第一件事就是跑它。它会检查 SDK 路径是否有效、Java 是否能找到、密钥是否配好、设备定义是否能读到。哪一项不对它会直接指出来比你在编译报错里大海捞针快得多。特别是刚换机器或者刚升级扩展之后先跑一遍能省掉半小时。4. 工程骨架manifest.xml 与 monkey.jungle走到这一步环境基本通了。接下来要理解一个佳明工程的骨架长什么样。这是一个很容易被用模板一键生成掩盖过去的环节但一旦你要加设备、改应用类型、调资源路径就绕不开这两个文件。4.1 先用模板生成一个能跑的最小工程别一上来就手写目录结构。命令面板执行Monkey C: New Project它会依次问你项目类型应用 / 小工具 / 表盘 / 数据字段、目标设备、SDK 版本、开发者密钥、项目位置。一路选完一个能编译能跑的最小工程就出来了。拿到模板后做两件事先原封不动编译跑一次确认从零到模拟器这个链路上没有任何环境问题。这一步是基准线后面出问题时可以拿它做对照。把生成的文件通读一遍尤其是manifest.xml、monkey.jungle和入口.mc文件。模板会生成一堆你可能不需要的设备声明和注释读完再删别删完才发现某个字段是必需的。模板生成的项目结构大致是这样MyProject/ ├── manifest.xml ├── monkey.jungle ├── source/ │ └── MyApp.mc ├── resources/ │ ├── strings/strings.xml │ ├── drawables/drawables.xml │ └── layouts/layout.xml ├── bin/ # 编译产物 └── .vscode/settings.json4.2 manifest.xml 逐字段拆解这个文件描述的是这个应用是谁、支持哪些设备、需要什么权限。关键字段如下字段作用踩坑点id应用的唯一标识一串 UUID改它等于换了一个应用旧版本无法覆盖升级多设备调试时别乱改type应用类型app/widget/watchface/datafield类型决定了入口基类写错会编译通过但运行异常entry入口类的类名必须和.mc里定义的类名完全一致大小写敏感name应用显示名走资源引用如Strings.AppName不要写死中文launcherIcon图标资源引用一般写成Drawables.LauncherIconminApiLevel最低要求的 API 等级用新 API 时忘了调高编译会报符号找不到products支持的设备列表目标设备不在这里模拟器里选它就报不支持permissions申请的权限代码里用了传感器却没声明运行时报权限错误languages支持的语言列表声明了语言要在strings.xml里有对应条目products那一块值得多说两句。它长这样iq:products iq:product idfr965/ iq:product idfenix7/ /iq:products每加一个设备编译时就多一份产物。设备加得越多编译时间越长所以开发阶段建议只留一两个目标机型发布前再补全。权限声明是新手最容易忘的。Monkey C 的权限是声明式的代码里调了Toybox.Sensor却没在manifest.xml里写iq:permissions iq:uses-permission idSensor/ /iq:permissions在模拟器上可能表现正常一到真机就报错或者功能静默失效。常见需要声明的有Sensor心率、加速度等、PositioningGPS、Communications和手机端通信、UserProfile用户资料、Background后台运行、Fit、SensorHistory等等。原则很简单代码里碰过哪一类数据就声明哪一类权限。4.3 monkey.jungle一行行的构建描述manifest.xml管的是应用元信息monkey.jungle管的是构建时把哪些东西编进去。最小的一份长这样base.sourcePath source base.resourcePath resourcesbase表示所有设备的默认配置sourcePath和resourcePath都是相对于 jungle 文件所在目录的路径。写错路径的典型症状是编译报一堆找不到符号因为编译器根本没读到你的源文件。多设备时可以给特定设备加专属的源文件或资源目录base.sourcePath source base.resourcePath resources fr965.sourcePath source source-fr965 fr965.resourcePath resources resources-fr965含义是fr965这台设备除了用公共的source和resources额外再读一个专属目录。这个机制在两种场景下特别有用一是某些设备屏幕形状特殊圆形、半圆、方形需要专门的布局二是某些设备的传感器能力不同需要条件编译式的代码分支。关于条件编译Monkey C 支持在源文件里用带后缀的写法区分设备也可以在代码里判断当前设备型号。前者更干净后者更灵活具体用哪种看你的分支复杂度。4.4 资源目录的约定资源用 XML 声明用语法引用。常见的几种字符串resources/strings/strings.xml里面定义string idAppName我的工具/string代码或 XML 里用Strings.AppName引用。想支持多语言就在同一个文件里按语言分组或者拆成多个文件。图片resources/drawables/drawables.xml声明图片文件放同目录。启动图标通常是 40×40 像素的 PNG具体尺寸和格式以模板和离线文档为准别自己乱定尺寸不对可能正常编译但在真机上不显示。布局resources/layouts/layout.xml用声明式的方式描述界面元素比纯代码画界面省事。菜单resources/menus/menu.xml定义长按菜单项。设置项resources/settings/settings.xml定义在手机端应用里能看到的配置项比如单位、开关。这里有个经验界面代码能用 layout 就别全用代码画。原因不是好看而是不同设备的分辨率和屏幕形状差异很大用 layout 配合相对定位换设备时改动量小得多。用像素绝对坐标画出来的界面在圆屏上很可能边角被切掉。5. 编译、模拟器与真机把包跑起来前面都是准备工作这一节是从代码到能看见的过程。我建议你至少完整走一遍命令行知道扩展在背后干了什么。5.1 用一条命令行还原 Build 的全过程VS Code 里点Build的时候扩展实际执行的是类似这样一条命令monkeyc \ -f monkey.jungle \ -d fr965 \ -y C:/Garmin/keys/mykey.der \ -o bin/app.prg \ -w参数含义逐个说清楚-f指定 jungle 文件编译器据此知道源文件和资源在哪。-d指定目标设备 id必须与manifest.xml的products里声明的一致。-y指定开发者密钥.der文件这一步产生签名。-o指定输出路径通常在bin/下。-w打开编译警告显示。强烈建议一直开着很多运行期崩溃的根源在编译警告里已经有提示了比如未使用的变量、可疑的类型转换。如果是多设备工程编译器会为每个声明的设备各产出一个 prg文件名通常带设备后缀便于区分。这就是为什么设备加多了编译会变慢。想验证扩展的配置是不是真的生效最直接的办法就是在终端里手敲一遍上面这条命令。如果命令行能过、VS Code 过不了问题在扩展配置如果两边都过不了问题在代码或环境。这个二分法我用了很多次次次有效。5.2 模拟器不只是能跑就行编译通过之后用运行类命令把模拟器拉起来。这个模拟器是一个独立的窗口程序虚拟了一台佳明设备包括屏幕、按键、传感器数据源。用模拟器的时候有几个点必须注意第一一定要在目标机型上跑。不同设备的屏幕形状差别很大——有圆屏、方屏、半圆屏比如顶部是平的圆分辨率从一百多像素到四百多像素不等按键数量和布局也不一样。你在一个机型上调好的界面换个机型可能直接错位或者文字被裁掉。模拟器里切换设备的入口很显眼别嫌麻烦。第二善用传感器模拟面板。模拟器可以手动设定心率、步数、GPS 轨迹、海拔、加速度、电池电量甚至导入 GPX 或 FIT 轨迹文件回放。这意味着你不需要真的戴着表跑十公里就能验证心率超过阈值时表盘变色这类逻辑。调试这类型的界面时把心率值手动拉到阈值上下反复横跳比看代码推理快得多。第三关注内存面板。佳明设备的内存上限是按机型定的通常在几十 KB 到几百 KB 这个量级比手机小几个数量级。模拟器一般会显示当前应用占用的内存。开发时如果发现内存曲线一路向上不回头多半是对象被意外长期持有比如把大数组挂在了全局对象上。第四看控制台输出。代码里的打印语句会出现在模拟器的控制台或者 VS Code 的输出面板里。把日志等级调高编译时用-l 3这类参数能看到更详细的信息包括系统事件和部分运行时警告。新版 SDK 的模拟器支持热重载改完代码重新构建后模拟器会自动刷新应用迭代速度很快。如果你的版本没有这个能力老老实实重新走一遍编译和运行也就十几秒的事不影响节奏。5.3 真机侧载prg 是怎么进手表的模拟器跑通了下一步就是上真机。经典做法是侧载用数据线把手表连到电脑。多数机型会以 U 盘或者 MTP 设备的形式挂载出来。打开设备存储找到GARMIN目录进去找APPS子目录。把编译出来的.prg文件拷进去。安全弹出设备断开连接。手表侧等待系统重新索引然后从应用列表或者小工具循环里就能找到。几个实操细节都是踩过才记得住的拷贝前先删掉同名旧文件。有些系统下直接覆盖会出现文件损坏或者新旧混用的情况先删再拷最保险。表盘和小工具的入口不一样。表盘要去表盘列表里切换小工具是长按上/下键在循环里翻应用是从应用列表点进去。装了看不到先确认你找的地方对不对。侧载对线材和接口比较敏感。MTP 模式在某些系统上本身就不太稳传输失败时先换线、换 USB 口别急着怀疑代码。真机上的日志不好拿。模拟器能看的控制台输出在真机上一般看不到那么详细。所以真机出问题的标准流程是先想办法在模拟器上复现复现不了就用注释掉一半代码的二分法定位到具体模块。顺带说一句真机测试最容易暴露的问题不是逻辑错误而是权限和内存。模拟器对权限的校验比真机宽松内存上限往往也更宽容所以模拟器一切正常、真机白屏或者秒退这两个方向要优先怀疑。5.4 打包成 iq 提交上架如果要发布到应用商店需要产出.iq包。原理和编译 prg 类似只是换了导出模式编译器有专门的导出参数并且需要完整的签名和元信息。打包前值得检查的事项manifest.xml里的products是否覆盖了所有想支持的设备。id是否和已上架版本的保持一致首次上架无所谓之后的版本千万不要改。版本号是否已经递增。签名用的密钥是否和之前版本用的是同一对。所有的语言声明是否都有对应的字符串资源避免出现空白文本。打包产物的体积通常不大因为佳明应用本身就很轻量这算是这个平台的一个好处——你不用花太多心思在包体积优化上注意力可以全放在功能和内存上。6. 报错排查按现象倒推根因开发过程中会遇到的问题基本可以归成几类。我把它们整理成一张对照表遇到报错时先在里面找最接近的那一行再去对应的子节看细节。现象大概率根因处理方向模拟器里找不到目标设备SDK 版本低于设备 CIQ 版本或products没声明换更高版本 SDK补全设备声明编译报符号找不到minApiLevel低于该 API 要求或拼写错误查该 API 的起始版本调高minApiLevel运行时报权限错误manifest.xml缺权限声明补uses-permission模拟器正常真机白屏或秒退内存超限、权限、引用了设备不支持的模块二分法定位优先查内存和权限SDK Manager 打不开Java 未装、JAVA_HOME错误、32 位 Java重装 64 位 JDK重配环境变量扩展提示找不到编译器sdkPath写错或路径含空格核对路径改成正斜杠移到无空格目录编译报密钥相关错误developerKeyPath未配或文件损坏重新生成密钥并配置路径真机装了但列表里找不到拷错目录、同名文件冲突、需要重启确认拷到GARMIN/APPS删旧再拷重启设备6.1 找不到设备和这个应用不支持该设备这是最高频的一类。它的本质是设备白名单机制manifest.xml里的products是一个明确的列表只有列表里的设备才被认为支持这个应用。模拟器切换到一个不在列表里的设备时会直接拒绝加载。排查顺序打开manifest.xml确认目标设备的 id 在products里且拼写和大小写完全正确。设备 id 一般是小写字母加数字比如fr965、fenix7写成FR965是不认的。确认-d参数或 VS Code 里选的设备和列表里的某一项完全一致。如果列表里有、设备也选对了还是提示不支持那就要怀疑 SDK 版本了。有些机型需要更高版本的 SDK 才有对应的设备定义文件换一个更新的 SDK 试试。还有一种情况是设备定义文件存在但该设备的 CIQ 版本高于你声明的minApiLevel上限……这种情况相对少见但如果你的minApiLevel设得异常高也可能被拒。我遇到过最隐蔽的一次是设备 id 里多了一个看不见的字符——从网页复制粘贴设备 id 的时候带进来的。所以如果你的配置看起来完全正确却不生效把那一行删掉重新手敲一遍这个动作只要十秒钟但能省掉半小时的怀疑人生。6.2 符号与 API 版本类的错误编译器说某个类或者某个方法不存在但你在文档里明明查到了。这种矛盾几乎总是出在minApiLevel上。机制是这样的每个 API 都有一个从哪个版本开始可用的标记。编译器会拿你的minApiLevel去卡这些 API如果你声明的最低版本里还没有这个 API它就认为这个符号在你支持的最老设备上不存在于是报错。处理方式有两种选哪种取决于你的目标用户调高minApiLevel放弃老设备支持。适合你确定用户机型都比较新的情况改动最小。写兼容分支在代码里判断当前设备是否支持这个 API不支持时走降级逻辑。适合要兼顾老机型的情况但代码会变复杂。判断某个 API 从哪个版本开始可用最靠谱的来源是 SDK 里的离线文档里面每个方法都会标注起始版本。6.3 运行期崩溃与内存问题编译期的问题都好办有明确的报错行号。运行期的崩溃麻烦得多尤其是只在真机上出现的那种。我的排查套路是固定的三步第一步看是否只在真机复现。如果模拟器里稳定复现问题基本在代码逻辑可以直接在模拟器里打断点或者加打印。如果只有真机出问题先怀疑内存和权限。第二步用注解法缩小范围。把getInitialView返回的界面先换成一个最简单的静态文本看还崩不崩。不崩说明是界面构建过程的问题崩说明是更底层的问题比如入口类初始化时的逻辑。然后逐段把代码加回来二分定位。第三步盯内存。佳明设备的内存是硬约束超了就是直接崩没有降级运行这种缓冲。常见的超限原因有把整段轨迹数据一次性读进内存、在onUpdate里每帧创建新对象、缓存了大量图片资源。优化思路也很直接数据分批处理、把可以复用的对象提到循环外面、图片按需加载。6.4 环境类问题的排除顺序如果问题发生在编译之前那就是环境问题。按这个顺序查最有效率java -version—— Java 通不通。monkeyc --version—— 命令行工具通不通。VS Code 里跑Monkey C: Verify Installation—— 扩展的配置对不对。检查 SDK 路径和密钥路径里有没有空格和中文。检查工作区级的settings.json有没有把用户级配置覆盖成错的。这五步走完98% 的环境问题都能定位。剩下那 2% 通常是多版本 SDK 互相干扰表现是昨天还能编译今天突然报奇怪的错这时候检查一下PATH里生效的是哪个版本以及工作区配置指向的是不是你以为的那一个。7. 日常开发里的一些真实体会环境搭好只是起点真正决定效率的是后面这些不起眼的习惯。7.1 设备矩阵要当成资产来维护一旦你的应用支持超过三款设备设备 id 列表就不再是随手能记住的东西了。我的做法是在项目根目录放一个设备清单文件把设备 id、显示名、支持的 CIQ 版本、屏幕形状记成一张表同时在manifest.xml里保持一致。加新设备时从这张表里取而不是凭记忆敲。编译多设备时如果嫌慢可以写个简单的脚本循环调用monkeyc只编你当前关心的那几个设备。这在迭代阶段能省下不少等待时间尤其是设备列表长了之后。7.2 日志要用等级控制不要靠删开发时满屏打印、发布时手工删干净这套做法在这个平台上风险很高——你很可能删漏也很可能在删的过程中顺手删掉别的逻辑。更好的方式是给日志分等级调试信息用低等级关键流程用高等级编译时通过-l参数控制输出到哪一级。这样发布版本编译时把等级调高调试信息自动不输出代码一行不用改。7.3 那几个容易把你带偏的搜索词写这篇文章的时候我顺手看了下相关的搜索词发现有一半以上其实是别的场景容易把人带沟里。整理一下省得你浪费时间搜索词实际场景和佳明开发的关系VS Code 改成中文只想换界面语言无关语言包不翻译 Monkey C 扩展命令VS Code 配置 C/C 环境写 C/C 项目无关Monkey C 不是 C不需要这套配置Flutter 报 unable to find suitable Visual Studio toolchainFlutter 在 Windows 上构建桌面端找 MSVC无关而且它找的是 Visual Studio不是 VS CodeSTM32CubeIDE for VS Code嵌入式 C 开发无关但如果你同时做硬件和佳明表盘两者可以共存LVGL PC 模拟器嵌入式 GUI 开发无关佳明有自己的一套 UI 框架VS Code 怎么写 C 语言C 语言入门无关但会装 VS Code 和配环境变量这部分经验可以复用真正值得搜的关键词是Connect IQ、Monkey C、monkey.jungle、manifest.xml、具体的 API 名比如Toybox.Sensor以及具体设备 id。这几个词的搜索结果质量明显高一个档次。我个人在整套流程里感受最深的一点是这个平台的工具链其实很克制没有花哨的功能也没有复杂的依赖管理但它对配置正确性的要求很高——设备 id 差一个字符、路径多一个空格、权限漏一条都会以很不直观的方式报出来。所以我现在养成了一个习惯每搭一次新环境先用模板生成一个最小工程完整跑一遍编译、模拟器、真机侧载这三步把基准线验证干净再往里加自己的代码。这个先跑通空壳再填内容的顺序比我早期直接开写省了不知道多少时间。另外一个小技巧把monkeyc的完整编译命令写在项目根目录的一个脚本文件里VS Code 出问题时直接跑脚本能立刻判断问题出在扩展还是在代码——这招在你重装系统或者换电脑的时候尤其管用。
佳明 Connect IQ 开发环境搭建：VS Code 与 Monkey C
手表上那个会随心率变色的表盘、跑步时能自动分段的小工具本质上都是跑在佳明设备 Connect IQ 虚拟机上的小程序而写这些程序的官方工具链里Visual Studio Code 已经成了比 Eclipse 更顺手的那条路。这篇文章讲的就是怎么在自己的电脑上把佳明穿戴设备 APP 开发平台搭起来从 Java 运行时、Connect IQ SDK Manager、SDK 版本选择到 VS Code 里的 Monkey C 扩展、开发者密钥、manifest.xml 与 monkey.jungle 的写法再到编译、模拟器联调、真机侧载和打包上架最后是那堆让人抓头的报错怎么按线索倒推。目标读者是手里有一块佳明表、想给自己或朋友写个小工具的人也适合做智能穿戴设备设计方案时需要一个可跑通的验证环境的人。前置知识只需要会装软件、会在命令行敲两条命令Monkey C 这门语言本身可以边写边学。1. 先搞清楚这套工具链里谁在干活很多人第一次搭佳明开发环境时会下意识地把它当成装个 IDE 然后就能写代码的常规流程结果 VS Code 装好了、扩展也装了一编译还是报错因为没弄明白真正干活的是哪个进程。这个认知如果一开始就建立起来后面九成的环境类问题都能自己定位。1.1 Monkey C 不是 C别拿 C 的思路往上套佳明穿戴设备上的应用语言叫Monkey C源文件后缀是.mc。名字里带 C但它跟 C 语言的关系大概只有都能写逻辑这一层。Monkey C 是动态类型的变量声明用var运行时才确定类型它有垃圾回收没有指针没有手动内存管理也不能开线程。写法上更接近 JavaScript 和 Java 的混合体代码被编译成字节码跑在设备固件里的一个虚拟机上。这个差异会直接影响你的编码习惯。举个例子C 里习惯的申请一块缓冲区循环复用在 Monkey C 里通常换成Toybox.Lang.Array或者ByteArrayC 里靠线程解决的耗时任务在 Monkey C 里靠回调和事件循环解决。日常最常用的几个库是Toybox.System时间和系统信息、Toybox.WatchUi界面、Toybox.Graphics画图、Toybox.Sensor传感器、Toybox.Activity当前运动数据、Toybox.Communications和手机端通信、Toybox.Math、Toybox.Time。你可以在 SDK 目录的doc文件夹里找到完整的 API 文档离线可查比在线翻快得多。编译产物有两种.prg是设备上实际运行的包.iq是提交到应用商店的打包格式。两者的关系有点像 APK 和签名后的发布版 APK。1.2 四件套的分工边界整套环境其实由四个互相独立的东西组成搞清楚各自的职责报错时才知道该往哪查。组件形态职责出问题的典型症状Connect IQ SDK Manager一个 Java 桌面程序下载、管理不同版本的 SDK双击没反应、启动就闪退Connect IQ SDK一个目录含命令行工具提供monkeyc编译器、模拟器启动器、设备定义、示例工程提示找不到monkeyc模拟器 Simulator独立进程由 SDK 里的命令拉起在电脑上虚拟一台佳明设备跑你的 prg设备列表里没有目标机型开发者密钥一对.der/.pem文件给编译产物签名设备只认签名过的包编译报签名相关错误注意 SDK 本身不带图形界面它给你的是一堆命令行工具。VS Code 的 Monkey C 扩展做的事情说白了就是帮你把这些命令行参数拼好、把输出显示在面板里。理解这一层意味着任何 VS Code 报错你都能退回到命令行自己复现一遍这是排查环境问题最有效的姿势。1.3 为什么是 VS Code 而不是 Eclipse佳明的 Connect IQ 开发最早主推 Eclipse 插件那个插件到现在还能用但装一次要拖一堆依赖启动慢而且 Eclipse 本身对其他语言的体验一般。VS Code 扩展的好处是轻、启动快、可以同时开好几个项目窗口更重要的是它生成的构建命令是可见的——你在终端里能看到它实际执行了什么。但别把 VS Code 想得太神。它不会帮你下载 SDK不会帮你装 Java很多环境变量还是得自己配。它就是个体面的外壳真正编译你代码的是monkeyc。顺带处理一个高频误解佳明开发不需要在 VS Code 里配 C/C 环境也不需要写c_cpp_properties.json、装 Microsoft 的 C/C 扩展。那套东西是给 STM32、LVGL 模拟器、纯 C 项目用的跟 Monkey C 完全两码事。同理搜索结果里出现的 vscode flutter android 项目报错unable to find suitable visual studio toolchain那是 Flutter 在 Windows 上构建桌面端时找不到 MSVC 工具链找的是 Visual Studio不是 Visual Studio Code跟佳明开发一个字都不沾。2. 环境搭建Java、SDK Manager 与版本选择这一段是全程最容易劝退的地方因为报错往往发生在你还没开始写一行代码之前。我的建议是严格按顺序来每完成一步就验证一次别一口气装完再统一排错那样出问题时变量太多。2.1 Java 运行时的三个细节SDK Manager 是个 Java 程序所以第一步是装 Java 运行环境。三个细节值得注意第一装 64 位版本。32 位的 Java 在现代系统上启动 SDK Manager 可能出现内存不足或者直接闪退而且这个错误信息非常不友好。第二版本别太老也别太新。Java 8 是底线但新版 SDK 和扩展在 Java 11 或 17 上更稳。我自己的做法是装一个 JDK 17而不是只装 JRE——虽然 SDK Manager 本身只需要运行时但多几十兆换来的是遇到奇怪问题时不用再回头补装。第三配好JAVA_HOME。Windows 上在系统环境变量里新建JAVA_HOME值指向 JDK 安装目录不要带\bin然后把%JAVA_HOME%\bin追加到Path里。macOS 和 Linux 上同理写进 shell 的配置文件。配完开一个新的终端验证java -version能打印出版本号就说明通了。如果提示命令不存在先别急着装第二遍多半是终端没重启或者路径写错了比如把bin也塞进JAVA_HOME了。2.2 SDK 的安装路径有讲究从佳明开发者站点下载 SDK Manager跑起来之后它会让你选一个目录来存放 SDK 版本。这里有一条经验路径里不要出现空格、中文和特殊符号。原因不是 SDK 本身有问题而是整个工具链里有一堆脚本、配置文件和命令拼接过程路径带空格时如果某一层忘了加引号就会把路径从中间截断报出来的错误往往是什么找不到文件或者意外的参数查半天查不到根上。这类坑历史上在 Windows 用户里出现得特别多。推荐放在WindowsC:\Garmin\connectiq-sdkmacOS / Linux~/garmin/connectiq-sdkSDK Manager 支持多版本共存每个版本下载下来是独立的一个目录比如connectiq-sdk-win-8.x.x这样。目录结构大致是这样connectiq-sdk-版本/ ├── bin/ # monkeyc、connectiq、模拟器等命令行工具 ├── doc/ # 离线 API 文档 ├── samples/ # 官方示例工程强烈建议通读几个 └── resources/ # 设备定义、字体等资源samples那个目录别跳过。里面有几个完整的表盘和小工具示例是理解manifest.xml和monkey.jungle该怎么写的最快途径比看文档快。2.3 选哪个 SDK 版本从目标设备反推这是最需要动脑的一步。SDK 版本不是越新越好因为SDK 版本决定了你能用哪些 API而设备决定了它最多支持到哪个 API 等级。判断逻辑是这样的先确定你要支持哪些设备。如果你是自己用就是你手上那块表如果要给别人用看用户群里哪几款机型最多。查这些设备各自支持的 Connect IQ 版本在 SDK 的resources或者设备列表里能查到官方文档也有对应表。选一个不低于这些设备支持版本、同时尽量新的 SDK。低了会导致某些 API 用不了高了会导致编译出来的包在老设备上装不上。举个具体的情景你手上有两块表一块是几年前的入门款只支持到较低的 CIQ 版本另一块是近两年的旗舰。这种情况下最稳的做法是下两个 SDK 版本共存主力用新版开发需要兼容老设备时切换 SDK 路径重新编译一次看是否有 API 报错。VS Code 的扩展不同工作区可以配不同的 SDK 路径切换成本很低。这里有个隐藏的坑manifest.xml里有个minApiLevel字段它声明的是这个应用最低要求的 API 等级。如果你在代码里用了某个新 API但minApiLevel设得比它要求的低编译器会直接报符号找不到或者类似的错误。这个报错看起来像是这个类不存在实际是在告诉你你的目标 API 版本里没有这个类。看到这类错误第一反应应该是去查这个 API 是从哪个版本开始提供的而不是怀疑自己拼错了类名。2.4 要不要把 SDK 的 bin 放进 PATH把 SDK 的bin目录加到系统的PATH里好处是终端里可以直接敲monkeyc和connectiq。这个能力在排错时非常值钱当 VS Code 扩展报找不到编译器时你可以立刻开个终端敲一遍monkeyc --version如果这里也报错说明是环境问题如果这里正常说明是扩展的 SDK 路径配置问题。一下就缩小了范围。代价是路径里只能有一个版本多版本共存时PATH里放的应该是最常用的那个。其他版本靠 VS Code 工作区设置里的绝对路径来指定。我自己的习惯是PATH里放主力版本然后每接一个新项目先跑一遍monkeyc --version确认当前生效的是哪个。3. VS Code 这一侧扩展、配置与开发者密钥环境装好之后VS Code 这边其实要做的事情不多但每一件都很关键尤其是开发者密钥这一环新手特别容易忽略。3.1 装 Monkey C 扩展顺便说清中文语言包的事在 VS Code 的扩展面板里搜Monkey C认准发布者是 Garmin 的那个。装完之后你会得到几样东西.mc文件的语法高亮、几组以Monkey C:开头的命令、以及对monkey.jungle和manifest.xml的基本识别。关于把 VS Code 改成中文这事你可以做但要有心理预期中文语言包只翻译 VS Code 自身的界面Monkey C 扩展的命令名和输出日志仍然是英文。也就是说命令面板里你还是得搜Monkey C:构建输出还是英文。所以没必要为了这个纠结反而英文命令名更利于你复制到搜索引擎里查。真要装扩展面板搜Chinese装官方语言包重启后按提示切换即可。常用命令都在命令面板Windows/Linux 是CtrlShiftPmacOS 是CmdShiftP里输入Monkey C会列出一组常见的包括Monkey C: New Project—— 从模板新建工程Monkey C: Generate Developer Key—— 生成开发者密钥Monkey C: Verify Installation—— 检查环境是否完整Monkey C: Build Current Project—— 编译当前工程Monkey C: Build for Device/ 运行类命令 —— 编译并在模拟器里跑起来不同版本的扩展在命令名称上会有一点增减以你装的版本实际列出来的为准。3.2 settings.json 里真正要写的几行配置项在 VS Code 设置里搜monkeyC就能全部列出来。最核心的是这么几项写在工作区级的.vscode/settings.json里好处是跟着项目走换机器不会忘{ monkeyC.sdkPath: C:/Garmin/connectiq-sdk/connectiq-sdk-win-8.x.x, monkeyC.developerKeyPath: C:/Garmin/keys/mykey.der, monkeyC.currentDevice: fr965 }几个细节路径用正斜杠/或者双反斜杠\\单反斜杠在 JSON 里是转义字符会直接把配置写坏。sdkPath指向的是 SDK 的根目录不是bin目录。currentDevice决定默认编译目标填的是设备 id比如fr965、fenix7这种小写形式。这个值必须出现在工程的manifest.xml的products列表里否则编译时会被拦下来。有些版本的扩展会提供设备下拉选择你把currentDevice写对之后状态栏上会显示当前设备。工作区级配置适合团队协作用户级配置适合放在自己机器上做默认值。我一般两边都写用户级放 SDK 路径和密钥路径个人机器固定的东西工作区级放currentDevice和 jungle 路径跟项目相关的东西。3.3 开发者密钥它到底签了什么这一步新手最容易漏漏了之后的表现是编译到一半报签名相关的错误或者模拟器能跑、真机装不上。生成方式有两种效果一样命令面板执行Monkey C: Generate Developer Key按提示选目录、输入名字比如mykey。直接在终端里跑monkeyc -g mykey在-g后面跟文件名。跑完之后目录里会出现两个文件mykey.der和mykey.pem。.der就是要填到monkeyC.developerKeyPath里的那个编译时通过-y参数传给编译器.pem是私钥文件单独找个地方备份好不要放进公开仓库。为什么需要密钥因为佳明设备只运行经过签名的应用包这是设备侧的一道基本校验。这也意味着一旦你用某个密钥签名并上架了应用后续版本最好继续用同一个密钥避免出现身份不一致导致上传被拒的情况。多台电脑开发时把同一对密钥拷过去用不要每次换机器都重新生成。提示.pem文件丢了的后果比.der丢了好一些但两个都建议备份到私有位置。顺手在.gitignore里加上*.pem和*.der这个习惯能省掉很多麻烦。3.4 Verify Installation 这条命令的价值命令面板里有一条Monkey C: Verify Installation很多人装完扩展就直接去新建项目了从来不点它。我建议养成习惯环境搭完第一件事就是跑它。它会检查 SDK 路径是否有效、Java 是否能找到、密钥是否配好、设备定义是否能读到。哪一项不对它会直接指出来比你在编译报错里大海捞针快得多。特别是刚换机器或者刚升级扩展之后先跑一遍能省掉半小时。4. 工程骨架manifest.xml 与 monkey.jungle走到这一步环境基本通了。接下来要理解一个佳明工程的骨架长什么样。这是一个很容易被用模板一键生成掩盖过去的环节但一旦你要加设备、改应用类型、调资源路径就绕不开这两个文件。4.1 先用模板生成一个能跑的最小工程别一上来就手写目录结构。命令面板执行Monkey C: New Project它会依次问你项目类型应用 / 小工具 / 表盘 / 数据字段、目标设备、SDK 版本、开发者密钥、项目位置。一路选完一个能编译能跑的最小工程就出来了。拿到模板后做两件事先原封不动编译跑一次确认从零到模拟器这个链路上没有任何环境问题。这一步是基准线后面出问题时可以拿它做对照。把生成的文件通读一遍尤其是manifest.xml、monkey.jungle和入口.mc文件。模板会生成一堆你可能不需要的设备声明和注释读完再删别删完才发现某个字段是必需的。模板生成的项目结构大致是这样MyProject/ ├── manifest.xml ├── monkey.jungle ├── source/ │ └── MyApp.mc ├── resources/ │ ├── strings/strings.xml │ ├── drawables/drawables.xml │ └── layouts/layout.xml ├── bin/ # 编译产物 └── .vscode/settings.json4.2 manifest.xml 逐字段拆解这个文件描述的是这个应用是谁、支持哪些设备、需要什么权限。关键字段如下字段作用踩坑点id应用的唯一标识一串 UUID改它等于换了一个应用旧版本无法覆盖升级多设备调试时别乱改type应用类型app/widget/watchface/datafield类型决定了入口基类写错会编译通过但运行异常entry入口类的类名必须和.mc里定义的类名完全一致大小写敏感name应用显示名走资源引用如Strings.AppName不要写死中文launcherIcon图标资源引用一般写成Drawables.LauncherIconminApiLevel最低要求的 API 等级用新 API 时忘了调高编译会报符号找不到products支持的设备列表目标设备不在这里模拟器里选它就报不支持permissions申请的权限代码里用了传感器却没声明运行时报权限错误languages支持的语言列表声明了语言要在strings.xml里有对应条目products那一块值得多说两句。它长这样iq:products iq:product idfr965/ iq:product idfenix7/ /iq:products每加一个设备编译时就多一份产物。设备加得越多编译时间越长所以开发阶段建议只留一两个目标机型发布前再补全。权限声明是新手最容易忘的。Monkey C 的权限是声明式的代码里调了Toybox.Sensor却没在manifest.xml里写iq:permissions iq:uses-permission idSensor/ /iq:permissions在模拟器上可能表现正常一到真机就报错或者功能静默失效。常见需要声明的有Sensor心率、加速度等、PositioningGPS、Communications和手机端通信、UserProfile用户资料、Background后台运行、Fit、SensorHistory等等。原则很简单代码里碰过哪一类数据就声明哪一类权限。4.3 monkey.jungle一行行的构建描述manifest.xml管的是应用元信息monkey.jungle管的是构建时把哪些东西编进去。最小的一份长这样base.sourcePath source base.resourcePath resourcesbase表示所有设备的默认配置sourcePath和resourcePath都是相对于 jungle 文件所在目录的路径。写错路径的典型症状是编译报一堆找不到符号因为编译器根本没读到你的源文件。多设备时可以给特定设备加专属的源文件或资源目录base.sourcePath source base.resourcePath resources fr965.sourcePath source source-fr965 fr965.resourcePath resources resources-fr965含义是fr965这台设备除了用公共的source和resources额外再读一个专属目录。这个机制在两种场景下特别有用一是某些设备屏幕形状特殊圆形、半圆、方形需要专门的布局二是某些设备的传感器能力不同需要条件编译式的代码分支。关于条件编译Monkey C 支持在源文件里用带后缀的写法区分设备也可以在代码里判断当前设备型号。前者更干净后者更灵活具体用哪种看你的分支复杂度。4.4 资源目录的约定资源用 XML 声明用语法引用。常见的几种字符串resources/strings/strings.xml里面定义string idAppName我的工具/string代码或 XML 里用Strings.AppName引用。想支持多语言就在同一个文件里按语言分组或者拆成多个文件。图片resources/drawables/drawables.xml声明图片文件放同目录。启动图标通常是 40×40 像素的 PNG具体尺寸和格式以模板和离线文档为准别自己乱定尺寸不对可能正常编译但在真机上不显示。布局resources/layouts/layout.xml用声明式的方式描述界面元素比纯代码画界面省事。菜单resources/menus/menu.xml定义长按菜单项。设置项resources/settings/settings.xml定义在手机端应用里能看到的配置项比如单位、开关。这里有个经验界面代码能用 layout 就别全用代码画。原因不是好看而是不同设备的分辨率和屏幕形状差异很大用 layout 配合相对定位换设备时改动量小得多。用像素绝对坐标画出来的界面在圆屏上很可能边角被切掉。5. 编译、模拟器与真机把包跑起来前面都是准备工作这一节是从代码到能看见的过程。我建议你至少完整走一遍命令行知道扩展在背后干了什么。5.1 用一条命令行还原 Build 的全过程VS Code 里点Build的时候扩展实际执行的是类似这样一条命令monkeyc \ -f monkey.jungle \ -d fr965 \ -y C:/Garmin/keys/mykey.der \ -o bin/app.prg \ -w参数含义逐个说清楚-f指定 jungle 文件编译器据此知道源文件和资源在哪。-d指定目标设备 id必须与manifest.xml的products里声明的一致。-y指定开发者密钥.der文件这一步产生签名。-o指定输出路径通常在bin/下。-w打开编译警告显示。强烈建议一直开着很多运行期崩溃的根源在编译警告里已经有提示了比如未使用的变量、可疑的类型转换。如果是多设备工程编译器会为每个声明的设备各产出一个 prg文件名通常带设备后缀便于区分。这就是为什么设备加多了编译会变慢。想验证扩展的配置是不是真的生效最直接的办法就是在终端里手敲一遍上面这条命令。如果命令行能过、VS Code 过不了问题在扩展配置如果两边都过不了问题在代码或环境。这个二分法我用了很多次次次有效。5.2 模拟器不只是能跑就行编译通过之后用运行类命令把模拟器拉起来。这个模拟器是一个独立的窗口程序虚拟了一台佳明设备包括屏幕、按键、传感器数据源。用模拟器的时候有几个点必须注意第一一定要在目标机型上跑。不同设备的屏幕形状差别很大——有圆屏、方屏、半圆屏比如顶部是平的圆分辨率从一百多像素到四百多像素不等按键数量和布局也不一样。你在一个机型上调好的界面换个机型可能直接错位或者文字被裁掉。模拟器里切换设备的入口很显眼别嫌麻烦。第二善用传感器模拟面板。模拟器可以手动设定心率、步数、GPS 轨迹、海拔、加速度、电池电量甚至导入 GPX 或 FIT 轨迹文件回放。这意味着你不需要真的戴着表跑十公里就能验证心率超过阈值时表盘变色这类逻辑。调试这类型的界面时把心率值手动拉到阈值上下反复横跳比看代码推理快得多。第三关注内存面板。佳明设备的内存上限是按机型定的通常在几十 KB 到几百 KB 这个量级比手机小几个数量级。模拟器一般会显示当前应用占用的内存。开发时如果发现内存曲线一路向上不回头多半是对象被意外长期持有比如把大数组挂在了全局对象上。第四看控制台输出。代码里的打印语句会出现在模拟器的控制台或者 VS Code 的输出面板里。把日志等级调高编译时用-l 3这类参数能看到更详细的信息包括系统事件和部分运行时警告。新版 SDK 的模拟器支持热重载改完代码重新构建后模拟器会自动刷新应用迭代速度很快。如果你的版本没有这个能力老老实实重新走一遍编译和运行也就十几秒的事不影响节奏。5.3 真机侧载prg 是怎么进手表的模拟器跑通了下一步就是上真机。经典做法是侧载用数据线把手表连到电脑。多数机型会以 U 盘或者 MTP 设备的形式挂载出来。打开设备存储找到GARMIN目录进去找APPS子目录。把编译出来的.prg文件拷进去。安全弹出设备断开连接。手表侧等待系统重新索引然后从应用列表或者小工具循环里就能找到。几个实操细节都是踩过才记得住的拷贝前先删掉同名旧文件。有些系统下直接覆盖会出现文件损坏或者新旧混用的情况先删再拷最保险。表盘和小工具的入口不一样。表盘要去表盘列表里切换小工具是长按上/下键在循环里翻应用是从应用列表点进去。装了看不到先确认你找的地方对不对。侧载对线材和接口比较敏感。MTP 模式在某些系统上本身就不太稳传输失败时先换线、换 USB 口别急着怀疑代码。真机上的日志不好拿。模拟器能看的控制台输出在真机上一般看不到那么详细。所以真机出问题的标准流程是先想办法在模拟器上复现复现不了就用注释掉一半代码的二分法定位到具体模块。顺带说一句真机测试最容易暴露的问题不是逻辑错误而是权限和内存。模拟器对权限的校验比真机宽松内存上限往往也更宽容所以模拟器一切正常、真机白屏或者秒退这两个方向要优先怀疑。5.4 打包成 iq 提交上架如果要发布到应用商店需要产出.iq包。原理和编译 prg 类似只是换了导出模式编译器有专门的导出参数并且需要完整的签名和元信息。打包前值得检查的事项manifest.xml里的products是否覆盖了所有想支持的设备。id是否和已上架版本的保持一致首次上架无所谓之后的版本千万不要改。版本号是否已经递增。签名用的密钥是否和之前版本用的是同一对。所有的语言声明是否都有对应的字符串资源避免出现空白文本。打包产物的体积通常不大因为佳明应用本身就很轻量这算是这个平台的一个好处——你不用花太多心思在包体积优化上注意力可以全放在功能和内存上。6. 报错排查按现象倒推根因开发过程中会遇到的问题基本可以归成几类。我把它们整理成一张对照表遇到报错时先在里面找最接近的那一行再去对应的子节看细节。现象大概率根因处理方向模拟器里找不到目标设备SDK 版本低于设备 CIQ 版本或products没声明换更高版本 SDK补全设备声明编译报符号找不到minApiLevel低于该 API 要求或拼写错误查该 API 的起始版本调高minApiLevel运行时报权限错误manifest.xml缺权限声明补uses-permission模拟器正常真机白屏或秒退内存超限、权限、引用了设备不支持的模块二分法定位优先查内存和权限SDK Manager 打不开Java 未装、JAVA_HOME错误、32 位 Java重装 64 位 JDK重配环境变量扩展提示找不到编译器sdkPath写错或路径含空格核对路径改成正斜杠移到无空格目录编译报密钥相关错误developerKeyPath未配或文件损坏重新生成密钥并配置路径真机装了但列表里找不到拷错目录、同名文件冲突、需要重启确认拷到GARMIN/APPS删旧再拷重启设备6.1 找不到设备和这个应用不支持该设备这是最高频的一类。它的本质是设备白名单机制manifest.xml里的products是一个明确的列表只有列表里的设备才被认为支持这个应用。模拟器切换到一个不在列表里的设备时会直接拒绝加载。排查顺序打开manifest.xml确认目标设备的 id 在products里且拼写和大小写完全正确。设备 id 一般是小写字母加数字比如fr965、fenix7写成FR965是不认的。确认-d参数或 VS Code 里选的设备和列表里的某一项完全一致。如果列表里有、设备也选对了还是提示不支持那就要怀疑 SDK 版本了。有些机型需要更高版本的 SDK 才有对应的设备定义文件换一个更新的 SDK 试试。还有一种情况是设备定义文件存在但该设备的 CIQ 版本高于你声明的minApiLevel上限……这种情况相对少见但如果你的minApiLevel设得异常高也可能被拒。我遇到过最隐蔽的一次是设备 id 里多了一个看不见的字符——从网页复制粘贴设备 id 的时候带进来的。所以如果你的配置看起来完全正确却不生效把那一行删掉重新手敲一遍这个动作只要十秒钟但能省掉半小时的怀疑人生。6.2 符号与 API 版本类的错误编译器说某个类或者某个方法不存在但你在文档里明明查到了。这种矛盾几乎总是出在minApiLevel上。机制是这样的每个 API 都有一个从哪个版本开始可用的标记。编译器会拿你的minApiLevel去卡这些 API如果你声明的最低版本里还没有这个 API它就认为这个符号在你支持的最老设备上不存在于是报错。处理方式有两种选哪种取决于你的目标用户调高minApiLevel放弃老设备支持。适合你确定用户机型都比较新的情况改动最小。写兼容分支在代码里判断当前设备是否支持这个 API不支持时走降级逻辑。适合要兼顾老机型的情况但代码会变复杂。判断某个 API 从哪个版本开始可用最靠谱的来源是 SDK 里的离线文档里面每个方法都会标注起始版本。6.3 运行期崩溃与内存问题编译期的问题都好办有明确的报错行号。运行期的崩溃麻烦得多尤其是只在真机上出现的那种。我的排查套路是固定的三步第一步看是否只在真机复现。如果模拟器里稳定复现问题基本在代码逻辑可以直接在模拟器里打断点或者加打印。如果只有真机出问题先怀疑内存和权限。第二步用注解法缩小范围。把getInitialView返回的界面先换成一个最简单的静态文本看还崩不崩。不崩说明是界面构建过程的问题崩说明是更底层的问题比如入口类初始化时的逻辑。然后逐段把代码加回来二分定位。第三步盯内存。佳明设备的内存是硬约束超了就是直接崩没有降级运行这种缓冲。常见的超限原因有把整段轨迹数据一次性读进内存、在onUpdate里每帧创建新对象、缓存了大量图片资源。优化思路也很直接数据分批处理、把可以复用的对象提到循环外面、图片按需加载。6.4 环境类问题的排除顺序如果问题发生在编译之前那就是环境问题。按这个顺序查最有效率java -version—— Java 通不通。monkeyc --version—— 命令行工具通不通。VS Code 里跑Monkey C: Verify Installation—— 扩展的配置对不对。检查 SDK 路径和密钥路径里有没有空格和中文。检查工作区级的settings.json有没有把用户级配置覆盖成错的。这五步走完98% 的环境问题都能定位。剩下那 2% 通常是多版本 SDK 互相干扰表现是昨天还能编译今天突然报奇怪的错这时候检查一下PATH里生效的是哪个版本以及工作区配置指向的是不是你以为的那一个。7. 日常开发里的一些真实体会环境搭好只是起点真正决定效率的是后面这些不起眼的习惯。7.1 设备矩阵要当成资产来维护一旦你的应用支持超过三款设备设备 id 列表就不再是随手能记住的东西了。我的做法是在项目根目录放一个设备清单文件把设备 id、显示名、支持的 CIQ 版本、屏幕形状记成一张表同时在manifest.xml里保持一致。加新设备时从这张表里取而不是凭记忆敲。编译多设备时如果嫌慢可以写个简单的脚本循环调用monkeyc只编你当前关心的那几个设备。这在迭代阶段能省下不少等待时间尤其是设备列表长了之后。7.2 日志要用等级控制不要靠删开发时满屏打印、发布时手工删干净这套做法在这个平台上风险很高——你很可能删漏也很可能在删的过程中顺手删掉别的逻辑。更好的方式是给日志分等级调试信息用低等级关键流程用高等级编译时通过-l参数控制输出到哪一级。这样发布版本编译时把等级调高调试信息自动不输出代码一行不用改。7.3 那几个容易把你带偏的搜索词写这篇文章的时候我顺手看了下相关的搜索词发现有一半以上其实是别的场景容易把人带沟里。整理一下省得你浪费时间搜索词实际场景和佳明开发的关系VS Code 改成中文只想换界面语言无关语言包不翻译 Monkey C 扩展命令VS Code 配置 C/C 环境写 C/C 项目无关Monkey C 不是 C不需要这套配置Flutter 报 unable to find suitable Visual Studio toolchainFlutter 在 Windows 上构建桌面端找 MSVC无关而且它找的是 Visual Studio不是 VS CodeSTM32CubeIDE for VS Code嵌入式 C 开发无关但如果你同时做硬件和佳明表盘两者可以共存LVGL PC 模拟器嵌入式 GUI 开发无关佳明有自己的一套 UI 框架VS Code 怎么写 C 语言C 语言入门无关但会装 VS Code 和配环境变量这部分经验可以复用真正值得搜的关键词是Connect IQ、Monkey C、monkey.jungle、manifest.xml、具体的 API 名比如Toybox.Sensor以及具体设备 id。这几个词的搜索结果质量明显高一个档次。我个人在整套流程里感受最深的一点是这个平台的工具链其实很克制没有花哨的功能也没有复杂的依赖管理但它对配置正确性的要求很高——设备 id 差一个字符、路径多一个空格、权限漏一条都会以很不直观的方式报出来。所以我现在养成了一个习惯每搭一次新环境先用模板生成一个最小工程完整跑一遍编译、模拟器、真机侧载这三步把基准线验证干净再往里加自己的代码。这个先跑通空壳再填内容的顺序比我早期直接开写省了不知道多少时间。另外一个小技巧把monkeyc的完整编译命令写在项目根目录的一个脚本文件里VS Code 出问题时直接跑脚本能立刻判断问题出在扩展还是在代码——这招在你重装系统或者换电脑的时候尤其管用。
