Appwrite 自托管函数的三条硬规矩：从一个鸿蒙单词打卡案例说起

鸿蒙案例中心新上了一个「单词打卡学习：HarmonyOS + Appwrite 端云一体化」，端侧 ArkTS 加云侧自托管 Appwrite。它的价值不在那个背单词界面，而在案例页写明的几条云函数规范：ESM 默认导出、node-appwrite v11、Server SDK 用 API Key 读写数据库、execute=["any"]。这几句话几乎把自托管 Serverless 最容易踩的坑都点到了，值得逐条拆开看。

为什么要用默认导出，而不是具名导出

Appwrite 的 Node 运行时按模块加载函数入口，找的是 default 导出。写成 export const main = ... 这类具名导出，本地跑得好好的，上传后一执行就报找不到入口。案例页专门把「ESM 默认导出」列进规范，说明这不是可选项，是硬约束。顺带一个连带影响：既然是 ESM，包里就得有对应的模块声明，require 那套老写法在同一个文件里混用会直接崩。

API Key 配错，报错是 401 而不是「没权限」

案例把「API Key 权限配置与 401 排障」单列成一项，这个细节很真实。自托管环境里 401 最常见的两个来源：一是 Key 的 scopes 没覆盖到要操作的集合（比如只给了读，函数里却要写学习记录），二是 Key 建在了另一个项目下、或者环境变量没注入到函数容器里。排查顺序建议固定下来：先确认 Key 属于当前 projectId，再看 scopes 是否覆盖目标集合的读写，最后看函数容器里实际读到的环境变量值。跳过前两步直接改代码，通常白改。

运行时版本和上传方式是最容易被忽略的两行

案例页写的是 tar.gz 打包上传、运行时选 node-16.0。这两条看着琐碎，实际决定了函数能不能启动：运行时选错，代码再对也是启动失败；打包时把 node_modules 一起塞进去、或者在 macOS 上打包含进扩展属性，解压后都可能出问题。这里比较稳的做法是只打源码和依赖声明，靠平台安装依赖。

数据模型：三个集合，五十八个词

案例用的是文档型 NoSQL，三个集合分别是 users_col、words_col、learn_records_col，配 58 词的词库。这个划分方式可以直接借：users_col 放账号与连续打卡状态，words_col 放词条，learn_records_col 记录每个用户学过哪些词、测试答对与否。连续打卡天数不单独建表，而是从学习记录推导，好处是不会出现状态表和记录表对不上的情况。

案例页还提到，和华为云 FunctionGraph + APIG 那套方案比，Appwrite 用内建 HTTP 路由加文档数据库，省掉了独立 API 网关层。省掉一层意味着少一处配置，也意味着路由和鉴权要自己在函数里写清楚，别指望网关帮你挡。

验收看什么

案例给的完成标志是：登录、首页、闪卡、测试四个页面能跑通；6 个云函数加 3 个集合端云联调通过；58 词词库与连续打卡逻辑正确，学完一个词打卡状态更新。真正容易漏的是最后一句的状态更新——把「学完」和「打卡」当成两个独立动作写，很容易出现进度满了但天数没加。测的时候专门盯着这两处一起变，比点一遍界面有用。

一句话总结：这个案例练的不是 UI，是自托管 Serverless 的工程规范。把那几条规范和排障顺序记下来，换个业务场景也能直接用。。