第一次做微信小程序：从 Excel/CSV 轻协作到体验版审核
这是一篇给“第一次做微信小程序”的人看的复盘。真正难的可能不是写页面，而是把账号、备案、域名、HTTPS、后端、体验版、审核和线上发布串成一个闭环。
我最开始以为做小程序大概是这样：
真正做起来才发现，这个理解有点太轻巧了。第一次做微信小程序，最容易卡住的不是某个 API，而是整个链路：小程序账号、AppID、AppSecret、合法域名、HTTPS、备案、微信开发者工具、体验版、审核版本、线上版本，每一环都要对齐。
这次做的小程序叫「轻表格协作」。它的目标很小：上传 Excel/CSV，生成一个轻量表格草稿，别人可以通过草稿 ID 打开同一份草稿，编辑单元格，并看到谁改了什么。
我不想把这篇文章写成“十分钟从入门到上线”的教程，因为真实过程不是这样。它更像一场工程闭环练习：一边写功能，一边查官方文档，一边处理平台规则，一边补测试和文档，一边在真机上被现实教育。
一、先把产品边界砍小
一开始很容易想做“大而全”的东西：既然处理 Excel，那是不是要支持公式、样式、合并单元格、多 sheet、权限系统、实时协同、导出、历史版本？
如果第一次做小程序就这么想，基本会把自己拖进泥里。
所以第一版我把它定义成“轻表格”，不是“在线 Excel”。MVP 只保留几个动作：
这几个动作加起来，刚好能验证一个完整场景：用户上传一个表格，生成一份可协作的轻量草稿，别人能打开、编辑、查看变更，最后也能删除。
这个边界帮我避开了很多复杂问题。比如我没有一开始接第三方在线文档引擎，也没有试图复刻 Excel 的完整交互。第一版只需要一套清楚的数据模型：草稿、列、行、单元格、协作者、变更记录。
后来证明，这个决定很关键。因为小程序真正麻烦的地方，不只在产品功能本身。
二、工程结构先为闭环服务
这次的工程结构比较朴素：
- 微信原生小程序：负责选择文件、上传、展示草稿、编辑单元格。
table-core：负责解析 Excel/CSV、推断字段类型、生成草稿模型。- Fastify API：负责上传解析、草稿读写、微信登录、协作者登记、变更记录。
- PostgreSQL：保存草稿、列、行、单元格、协作者和变更。
- Docker Compose：在服务器上跑 API 和数据库。
- Nginx + HTTPS 证书：给小程序提供合法域名访问。
我刻意没有一开始上很复杂的架构。原因也简单：第一阶段的核心不是“架构好看”，而是把小程序、后端、数据库、微信后台、真机体验和审核流程跑通。
项目里还定了几个工程规则：
- 每次涉及平台、部署、隐私、审核的判断，都写进文档。
这些规则看起来慢，但在第一次做小程序时很救命。因为你一定会忘记自己当时为什么这么选，也一定会遇到“昨天还能跑，今天真机不行”的情况。文档和测试不是形式主义，它们是后面定位问题时的绳子。
三、微信开发者工具不是普通前端开发环境
第一个明显的坑来自微信开发者工具。
小程序项目导入后，页面一开始能打开，但主体内容空白。后来排查发现，小程序运行时不能随便从 miniprogramRoot 外部引用代码。普通前端项目里“路径引用能编译”不代表小程序运行时也能找到。
于是我把运行时代码移动到 miniprogram/lib/ 下，避免小程序包外引用。这个问题如果只靠肉眼看页面，很容易误以为是样式或生命周期问题；最后还是靠控制台错误和最小化路径排查定位。
另一个坑是 TypeScript 编译插件。开发者工具里如果 TypeScript 编译插件没有按预期启用，文件看起来都在，但运行结果会很奇怪。最后我把这个操作也写进了联调手册。
还有 CLI。微信开发者工具提供命令行上传和预览能力，但我本机多次遇到 CLI 长时间不返回。最后的策略是：CLI 可以作为辅助，但不要把它当成唯一发布路径。真实上传还是优先用 GUI，并记录失败命令和截图。
第一次做小程序，我的感受是：不要假设它等同于普通 Web 开发。它有自己的项目结构、运行限制、开发者工具状态和真机差异。
四、真机体验会暴露模拟器看不到的问题
模拟器里跑通之后，我以为差不多了。真机体验版很快给了我第二轮提醒。
第一个问题是文件选择。手机端选择 Excel/CSV 时，入口可能会跳到微信聊天文件，也可能提示用 WPS 等手机应用打开。这个体验跟桌面开发者工具完全不同。后来我把它理解成：小程序只能调用微信提供的文件选择能力，具体用户怎么从手机里拿到文件，会受微信、聊天记录、系统文件管理和第三方应用影响。
第二个问题是接口响应。真机里 wx.request 返回的数据有时是字符串 JSON，小程序端如果只按对象处理，就会误判失败。这个问题在模拟器里不一定稳定复现。最后我给请求层补了字符串 JSON 解析，并写了测试覆盖。
第三个问题更现实：未认证小程序的分享能力会受限制。最开始我设计的是“分享给协作者”，但真机提示未完成认证，分享能力暂时无法使用。
这时如果继续死磕分享，就会卡住整个协作验证。所以我补了一个兜底路径：复制草稿 ID。对方在首页粘贴草稿 ID，也能打开同一份草稿并编辑。
这不是最终理想体验，但它让 MVP 继续往前走。第一次做平台型产品，很重要的一点是区分“产品最终形态”和“当前可验证路径”。分享能力要继续处理，但协作闭环不能因此停摆。
五、后端、域名、HTTPS 是小程序上线的硬门槛
小程序正式环境访问后端，不是随便填一个接口地址就行。
这次后端部署在京东云，域名是 api.askmind.top。实际走过的链路是：
- 服务器用 Docker Compose 跑 API 和 PostgreSQL。
- Certbot / Let’s Encrypt 签发 HTTPS 证书。
- 微信公众平台配置 request、uploadFile、downloadFile 合法域名。
- 本地和真机分别验证
https://api.askmind.top。
这里面有几个经验：
第一，HTTPS 是必需项。小程序合法域名不能靠开发环境“关闭校验”蒙混过去。开发者工具里能跑，不代表真机和审核环境能跑。
第二，AppSecret 只能放后端。小程序前端拿到的是 AppID，微信登录需要后端用 AppSecret 去换 openid，再签发自己的业务 session。AppSecret 不能进前端，也不能进仓库，更不能出现在截图里。
第三，部署脚本要保留服务器 .env。代码可以从 GitHub 拉，镜像可以重建，但服务器上的数据库密码、AppSecret 等环境变量不能被覆盖。
第四，部署后要跑 smoke。不是看容器启动了就算成功，而是要真实请求健康检查、创建草稿、读取草稿、编辑单元格、读取变更记录。后面补删除功能后，smoke 也要顺手删除临时草稿，避免测试数据一直留在线上。
这些事情不是“后端附属工作”，它们就是小程序上线的一部分。
六、审核通过不等于上线，备案也不能拖到最后
这是我这次学到的一个平台流程重点。
小程序版本状态大概可以这样理解：
这几个词很容易混。
我们当前有一个 0.1.2 版本已经审核通过，但后台状态是“审核通过待发布”。也就是说，它通过审核了，但还不是线上版本。还需要在后台点击发布，普通用户访问的才会变成这个版本。
另外，小程序备案也要提前做。备案提交后会进入审核中，时间不一定短。未备案或未发布线上版时，不要把“普通用户能通过微信搜索发现”当作当前验收条件。这个阶段更适合用体验版、二维码和体验成员入口做联调。
这也让我意识到：做小程序不能只排研发计划，还要排平台流程计划。备案、审核、认证、发布，每一个都有自己的节奏。
七、为什么 MVP 也要做删除和隐私说明
一开始我也容易觉得：只是一个内测工具，先把功能跑通就行。
但这个小程序会保存用户上传的表格内容。即使是 MVP，也需要回答几个问题：
所以在正式提审前，我补了“删除草稿”能力。删除后会清理草稿、表格内容、协作者和变更记录。
当前第一版的删除权限是“持有草稿 ID 即可删除”。这不是最终权限模型，而是 MVP 阶段的取舍。原因是草稿创建阶段还没有强制登录，也没有完整 owner 记录。等后续进入正式多用户权限阶段，就应该改成只有创建者或管理员可以删除。
这件事给我的提醒是：隐私和删除不是上线前随手填一段文案。只要产品保存用户数据，就应该尽早把删除路径和权限模型想清楚，哪怕第一版很简单。
八、AI 协作的价值和边界
这次项目里，我大量使用 AI 协作完成代码、测试、文档、调研和部署记录。
它很适合做这些事：
但它也有很清楚的边界：
所以更有效的协作方式不是“让 AI 全自动做完”，而是把任务拆成两类：
这次每一张截图、每一次真机反馈，都会变成下一轮修复和文档。这个循环比单纯“让 AI 写代码”更重要。
九、给第一次做小程序的人一张清单
如果你也准备第一次做微信小程序，我会建议先检查这些事。
账号和平台：
后端和域名：
- request、uploadFile、downloadFile 合法域名已配置。
功能和体验：
工程和文档：
- 截图里没有 AppSecret、密码、验证码、登录二维码和真实用户隐私。
结尾
这次最大的感受是：第一次做小程序，写代码只是其中一部分。真正要跑通的是“产品想法 -> 工程实现 -> 平台规则 -> 真机体验 -> 审核上线”的完整链路。
如果你也准备第一次做小程序，建议先别急着堆功能。选一个足够小的场景，把上传、登录、数据保存、删除、审核说明和体验版真机联调跑通。能跑通闭环，再谈复杂能力。
对我来说，「轻表格协作」目前还只是一个很小的开始。但它让我把小程序从账号、后端、域名、备案、审核到真机协作完整走了一遍。这个过程比最后那个按钮本身更有价值。
