国
核心亮点
- 原文与注解分层展示,阅读门槛低
- TTS 生成朗读音频,可听可看
- 音频走 CDN 静态托管,播放不占后端
技术栈
产品界面
开发成果 4/6
- 内容架构搭建
- 朗读音频 TTS 生成
- 智能讲解音频托管 guoxue.filebreeze.cn
- 每日提醒后端通道(消息推送 + 订阅消息)
- 订阅消息模板 ID 接入并跑通首次下发
- 小程序发布流程(icon / 介绍 / 提审)
开发历程 12 条
证实朗读不烧 TTS 额度,并把切段逻辑收敛为单一来源
- 结论:朗读不烧 TTS 额度。三级链路只有第 3 级花钱,本地缓存 0 请求、服务器预置只下载自家域名,57 段覆盖 18 部书,正常停在第二级。
- 新建 tools/tts-verify-page.js 复刻页面侧组装逻辑,与 tts-check.js 交叉验证,实测请求 59 段、去重 57、服务器缺 0。
- parseContent 曾在两个详情页 + 构建脚本各存一份共 4 处,漂移会让 hash 对不上、静默走在线合成,已收敛到 utils/tts-common.js。
- 进度文案改为「已缓存 / 加载音频 / 在线合成」,只有最后一种消耗额度;另清理《论语》20 个孤儿音频,用 mv 备份可回退。
踩坑:报错代码把「域名未配」伪装成了「网络不好」
- 现象:开发者工具朗读正常,真机一律弹「合成失败,请检查网络」,但网络与域名都没问题。
- 根因在报错代码:wx.request/downloadFile 的 fail 传的是普通对象 {errMsg} 不是 Error,String(err) 得到 [object Object],匹配不上 not in domain list 便掉进兜底分支。
- 修法:所有 wx 出错路径统一过 errText() 归一化,fail 补主机名,域名类错误直接抛出不再降级重试。
- 经验:错误提示必须能反推根因,catch 不该产出「请检查网络」这类无信息量文案。
「每日提醒」后端从 0 到 1 打通
- 打通两条反向通道:消息推送(微信→服务器,配 URL/Token/AESKey)与订阅消息(服务器→用户,需 access_token + 模板 ID)。
- 后端 server/ 零依赖纯 Node,监听 8790,nginx 反代 /api/wx/,密钥只存服务器环境文件(600)不入库。
- systemd:guoxue-api 常驻 + guoxue-push.timer 每天 07:00(错峰、错过补跑)。
- 选 JSON 免 CDATA 转义;实测合法签名回 echostr、错误签名 403,access_token 换取成功。
- 离线自检 31 条全过(15 加解密 + 16 端到端),只差订阅消息模板 ID。
朗读音频托管落地:自定义域名实测与微信的配置约束
- 音频改静态托管:站点落 (服务器路径),音频目录 /tts/audio/{hash}.mp3。
- 实测 HTTPS 200、Content-Type: audio/mpeg、支持 Range(206),Let's Encrypt 由 certbot.timer 自动续期,TLS 1.2/1.3 正常。
- 服务器是腾讯云轻量北京地域,域名必须 ICP 备案。
- 微信约束:必须 HTTPS + 已备案,不能用 IP 与非默认端口,每类上限 20 个、每月只能改 5 次;本项目占两类共 3 个域名。
- 风险:轻量套餐有月流量包上限,超额断网时回退在线合成兜底。
修复「朗读全文失败」:两个根因叠加,都不是网络问题
- 真机点朗读一律弹「合成失败,请检查网络」,但网络与域名都正常,提示本身在误导排查。
- 根因一:《论语》补全 20 篇后段落 hash 全变,未重跑预合成,25 段一个都不在服务器。
- 根因二:百度长文本合成音频落在 aipe-speech.bj.bcebos.com,tsn.baidu.com 是短文本接口地址,填错被 wx.downloadFile 拦截。
- 修复:按 hash 判存只补 25 段,耗时 1 分 43 秒,覆盖率回到 100%(需 57 段、缺 0)。
- 新增 hostOf/reportError,域名类错误直接提示「音频域名未配置」并附主机名。
踩坑:icon 裁剪为什么「按卡片裁」是错的
- 坑 1:不能按卡片裁,要按内圆圆心 ± 半径裁,否则微信圆形裁切后露出米白纸底与云纹残线。
- 坑 2:粗检圆心偏 14px(被云纹细线打断),改两遍裁切:180 条射线测边界 + 最小二乘拟合圆,四边留白 7/7/8/6。
- 坑 3:微信圆角矩形展示会露四角纸底,按径向取半径 −14px 处颜色补角,最外 5 圈 20480 像素里米白 0 个。
- 验证手法:取橙色朝日质心相对圆心的归一化坐标,两版 dx=−0.194 完全一致。
icon 三轮迭代,最后定稿的是用户自己画的那一版
- icon 三轮迭代,最终定稿的是用户自己用豆包 AI 画的那一版。
- 第一轮图形 + 四字被否,小尺寸必糊;第二轮改日月符号 4 套,推荐日月合璧;第三轮按幼学启蒙重做 5 套,128/96/64/48px 实测,竹叶在 64px 以下糊成一团判不合格。
- 定稿为深青圆 + 金边,内含竹简卷轴、书卷、朝日、白月、云纹与朱砂篆印;5 套全部归档 design/icon/archive_yixiang/。
- 写了可复现裁剪脚本 design/crop_icon.py,输出符合规范的 1024×1024 成品。
定位澄清与命名定稿:从「画山别墅里的国学世界」到「朝夕国学」
- 核对注册状态发现小程序一直没在公众平台注册,本地 AppID 是早期占位值,且被 git skip-worktree 保护,状态看起来一直干净。
- 微信命名硬规则:4-30 字符(汉字算 2)、全平台唯一、不能单一通用词、禁用保留字,个人主体每年只能改 2 次。
- 定位从「国学书房」纠正为幼学启蒙,面向童蒙,名字、文案、视觉全跟着改。
- 定名「朝夕国学」,微信名称校验已通过。


