为什么会变成这样呢……
第一次有了相爱的老婆。
有了能一起经营的个人网站。

两件快乐事情重合在一起。
而这两份快乐，又给我带来更多的快乐。

得到的，本该是像梦境一般幸福的时间……
为什么，会变成这样呢……


这不是一篇冷冰冰的技术复盘，没有堆砌晦涩的术语，只是一段很私人的开发小故事。

起因很简单：我老婆嫌弃我做的网站太难用，懒得更新了。

于是我和大肥鱼“合砍”了一套手机端小程序式界面，专门适配我们的 Halo 站点。从被吐槽鸡肋，到“真香”、刷动态点赞，全程踩过的坑、摸透的规则，我都整理在了这里。

如果你也想给 Halo 做移动端瞬间功能，不想瞎摸索试错，这篇普通人的实战日记，希望能帮到你。

一、动机：好好的小网站，被「繁琐操作」逼停了


我和老婆一起打理着一个属于我们的小站点。

分工很简单：她负责用心记录生活、更新内容，我负责敲代码、维护后台安稳运行。

最开始新鲜感满满，可没过多久，我就发现站点的更新频次，肉眼可见地归零了。

我有点疑惑，问她怎么不更新了。

她放下手机，一脸无奈地跟我吐槽：

「太麻烦了，真的懒得弄。」

「我手机随手拍了一堆照片，想记录一下生活，结果还要打开电脑、登录后台、翻菜单找到瞬间功能，再上传图片、敲文字……只是发个日常而已，至于这么折腾吗？」

听完我瞬间就懂了。

Halo 原生后台是妥妥的桌面端设计，功能全面、管理专业，但完全不适合普通人随手记录生活。

我们不是全职博主，不需要复杂的排版、权限、归档功能。我们想要的，只是像发朋友圈一样：掏出手机，点几下，碎片生活即刻存档。

看着她明明想记录生活，却被繁琐的操作劝退，我心里就萌生了一个念头：

我给她单独做一个手机端「专属朋友圈」吧。

不用开电脑、不用反复登录、操作极简，能发动态、看动态、评论互动就够了。

做开发的意义不就是这样吗？用技术解决身边人的小麻烦，留住普通人的生活温柔。

二、需求：不用花里胡哨，只要「像朋友圈一样顺手」


这次开发我没有定什么宏大目标，所有需求都来自老婆的真实使用感受，简单、直白、接地气：

1. 全程手机优先

放弃电脑端适配，所有界面专为手机屏幕设计。大按钮、宽输入框、极简布局，全程拇指就能操作，不用精准点小按钮，杜绝误触卡顿。

2. 一次登录，长期省心

最烦重复登录。实现一次登录、持久生效，不用每次打开页面输密码、验证身份，打开就能用。

3. 只保留核心刚需功能

删掉所有冗余复杂的后台功能，只留三件事：发布生活瞬间、浏览全站动态、点赞评论互动。够用、好用、不花哨。

4. 可装手机桌面，像原生APP一样沉浸

不想通过浏览器标签页打开。做成可添加桌面的应用模式，打开无地址栏、无多余标签，全屏沉浸式使用，和普通APP毫无区别。

说白了，我的开发目标特别纯粹：复刻微信朋友圈的极简体验，但是所有数据、内容都牢牢握在我们自己的 Halo 站点手里。

技术选型上，我也刻意从轻从简。

页面功能不多，完全没必要上 React Native、Flutter 这类重型框架，徒增部署和维护成本。最终敲定 Flask + SQLite + 原生JS，整套项目轻量化、部署简单、后续迭代省心，对我这种个人开发者太友好。

本以为UI页面是最大的工作量，真正开发才发现：对接 Halo 各类API、适配插件逻辑，才是最磨人的坑。

三、踩坑：令牌有权限，却发不了评论

Halo 的官方文档、插件文档其实写得很细致，基础对接基本零障碍。但很多隐性问题，文档不会标注，只有你真正跑通业务逻辑、实测上线，才会暴露出来。

这次开发遇到最经典、最折磨人的bug，没有之一。

问题：明明有评论权限的PAT令牌，能正常调用各类接口，唯独无法发布评论，直接返回403无权限。

我反复核对了无数次：令牌权限范围完整、账号是权限足够、接口请求格式完全正确，理论上不可能报错。

我一度怀疑是官方令牌生成逻辑有bug，反复调试、比对参数，折腾了大半天毫无进展。

实在没头绪，只能硬着头皮去翻 comment-next 插件的源码。

终于在 CommentCaptchaFilter.java 里找到了隐藏的关键逻辑：

只要站点开启了「匿名评论需验证码」功能，除了前端登录 Basic Auth 的用户，所有携带 Bearer 请求头的请求，都会被插件误判定为匿名用户。

瞬间恍然大悟！

我的PAT请求，明明身份合法，却被插件当成了匿名访客，系统要求输入验证码，而我的请求里没有携带验证码参数，最终直接拦截、返回403权限不足。

摸清问题根源后，我梳理了两套解决方案：

方案一：直接关闭评论验证码功能。简单粗暴，一键解决，但会彻底失去验证码防护，站点垃圾评论、灌水评论会大幅增加，安全性大打折扣。

方案二：前端适配逻辑，检测到 captcha-required 状态时，自动弹出验证码输入框，用户输入验证码后携带Cookie重试请求。

我毫不犹豫选了第二种。

我特意问了老婆的使用感受，她觉得完全没问题：「偶尔输一次验证码根本不麻烦，总比开电脑登录后台强太多了。」

就这样，既保住了站点安全，又保留了极致的使用便捷性，算是这次踩坑最圆满的收尾。

四、PWA沉浸式适配：成功收获老婆一句「真香」

接口调试、功能开发、bug修复全部完成后，我最后做了一波体验优化：完整适配 PWA 渐进式Web应用。

配置好 manifest.json、Service Worker 缓存规则、多尺寸适配图标。

手机端用Chrome打开页面，一键「添加到主屏幕」，桌面上就多出了一个专属应用图标。

点开直接全屏启动，没有浏览器地址栏、没有多余标签页、没有任何冗余干扰，视觉和使用体验，和原生APP几乎一模一样。

老婆试用了一下，给了我最治愈的一句反馈：

「嗯，现在真的像朋友圈了，我以后用着方便多了。」

那一刻真的比写完任何复杂代码、调通任何接口都有成就感。

现在的她，会随手拍一拍窗外的夕阳、做好的饭菜、路边的花草，随手打开这个专属小应用，几句话、一张图，记录日常细碎。也会偶尔打开站点，翻翻别人的瞬间，点个赞、留个言。

我们冷清了很久的小网站，希望又能焕发生机。

当然，她也给我提了甜甜的「迭代需求」：想要评论表情包功能、想要拖动调整图片顺序……

这些甜蜜的小烦恼，就留给后续慢慢优化更新啦。

附录：亲测可用｜Halo移动端开发常用API速查

踩遍无数坑、反复实测调通后，整理出一套稳定可用的接口清单，给需要开发同款功能的朋友直接复用，省去反复试错的时间。

接口用途接口端点
校验令牌 / 获取当前登录用户信息GET /apis/uc.api.halo.run/v1alpha1/users/-
发布个人瞬间POST /apis/uc.api.moment.halo.run/v1alpha1/moments
获取全部公开瞬间列表（page从1开始）GET /apis/api.moment.halo.run/v1alpha1/moments
发表评论POST /apis/api.halo.run/v1alpha1/comments
回复评论POST /apis/api.halo.run/v1alpha1/comments/{name}/reply
获取评论列表（含子回复）GET /apis/api.commentnext.xhhao.com/v1alpha1/comments?withReplies=true&replySize=10
Picsur图片平台登录POST /api/user/login
Picsur 图片上传/列表查询/删除/api/image/upload、/api/image/list、/api/image/delete

项目开源 & 碎碎念

整套代码我已经开源，结构简单、轻量化，非常适合个人二次修改、自用：

GitHub 地址：https://github.com/yuubaris/Custom-Mobile-Halo-Client

如果你也想给 Halo 搭建简易移动端、做瞬间发布功能，希望我的这篇踩坑日记，能帮你快速定位，少走弯路。

最后想说一句很真心的话：

代码再优雅、技术再酷炫，都不如身边人一句「这个真的好用」。

从真实的生活痛点出发，用技术解决小小的麻烦、留住细碎的温柔，这大概就是普通开发者最朴素、最珍贵的开发意义。