七月底那篇 2026 开发复盘 写的是「半年五个项目」的长线回顾。而这周的情况很不一样：三个项目几乎同时开工、同时推进、同时收尾，其中两个还涉及我之前完全没碰过的领域。

这篇只讲三件事：做了什么（一句话）、遇到了什么问题、以及 vibe coding 到底靠不靠谱。不想写成功能清单，很多细节也没必要展开。

三个项目，三句话

三个项目几乎没有重叠的技术栈：一个桌面端、一个实时联机、一个 NAS 生态。这也是我刻意为之——想看看 vibe coding 在不同领域的表现。

一、织词：桌面端的性能与数据

桌面应用的第一个体会：本地数据越多，越考验工程能力。角色、标签、翻译映射、别名……数据量上来之后，从「能跑」到「不卡」之间隔着一次重构。

遇到的问题：

• 状态管理失控：功能越加越多，一个主组件膨胀到几百行、七八个 useState，改一处崩三处。最后老老实实重构，拆成多个 store 才稳住。
• 渲染性能：列表数据大之后，滚动明显卡顿，不得不引入虚拟滚动。
• 中文搜索远比想象复杂：汉字、拼音、首字母、别名、同义词，每个都要命中；还遇到过某条全量查询耗时 20 秒的超时问题，最后靠给匹配逻辑加门控条件解决。
• 中英双语的一致性：输出是中英双份的，两边经常对不上。后面做了不少数据审计工作，才把差集清零。

心得：数据质量工程（data engineering）的坑，不比写代码少。vibe coding 能很快写出功能，但「数据对不对、全不全、一致不一致」这件事，AI 帮不了多少，得自己一遍遍核对。

二、游戏大厅：P2P 联网是深水区

这个项目的定位很简单：朋友之间通过邀请码注册，建立房间，然后双方设备点对点直连对局，服务器只做控制面。

遇到的问题：

• 库与环境的版本暗坑：密码哈希库在 CI 的 Node 版本下直接报「不是函数」，查了半天是版本兼容问题，升级运行时才解决。
• 白屏问题：为安全加了严格的内容安全策略（CSP），结果某些环境下一打开就是白屏，排查下来是安全策略和浏览器扩展冲突，最后做了权衡调整。
• P2P 连不上：不同运营商、不同 NAT 环境下，直连经常失败。只能做成「局域网直连 → 点对点 → 中继兜底」三级策略，再加网络检测向导让用户自己看链路质量。
• 平台限制：部署平台对 WebSocket 连接时长有硬限制，不得不设计短连接 + 退避重连 + 消息重放的方案。
• 测试不稳定：端到端测试经常时好时坏，同一套用例在本地全过、CI 上随机挂，花了不少时间稳定它们。

心得：联网和安全的坑，vibe coding 只能帮你走到一半。AI 能写出 WebRTC 握手、能写出认证流程，但「为什么这个环境下连不上」「为什么 CI 上测不过」这种需要实机环境反复验证的问题，最后还是得靠人一点点试。

三、阅海：改一个大项目的勇气

这个项目是给 NAS 做的图书馆应用，基于开源的阅读器 fork 改造。这是三个项目里**最「改别人的代码」**的一个。

遇到的问题：

• gitignore 误吞：一次配置失误，把源码文件整个从版本控制里吞掉了，差点丢文件，花了不少力气恢复。
• 安全漏洞：fork 上游的代码里存在认证相关的漏洞，逐项审计修复，顺手把沙箱和内容安全也补上了。
• 上游版本管理：fork 了多个开源项目，版本固定、许可证分层、上游更新跟踪，全是琐碎但必须做对的事。
• NAS 集成：安装向导、权限、数据卷、生命周期脚本，和普通 Web 应用完全不是一个思路。

心得：改别人的大项目，最大的瓶颈是上下文。项目太大，AI 的上下文窗口根本装不下整个代码库，经常「改了这个忘了那个」。只能把改动拆得很碎，一次只动一个点，每步都靠测试兜底。

vibe coding 到底有什么问题

三个项目跑下来，说说我的真实感受：

1. 功能写得快，问题出在后面。 一周能堆出别人一个月的功能量，但随之而来的性能、数据一致性、边界情况，AI 不会替你想到。

2. 测试是唯一的救命稻草。 没有测试，vibe coding 就是给未来的自己埋雷。三个项目都是测试越写越重，到后期几乎改一个点就要跑一遍全量回归。

3. 上下文是硬天花板。 单文件、单模块 AI 很强；整个项目级别的「全局视野」，AI 给不了，得靠人拆分和设计。

4. 安全和隐私不能外包。 代码生成得再快，认证、权限、密钥管理这些还是要自己过一遍，不能假设 AI 写的就是安全的。

5. 数据比代码更费神。 尤其涉及大量结构化数据时，AI 写转换代码很利索，但数据本身的正确性，只能靠审计。

最后

这周最大的收获不是三个项目本身，而是摸清了 vibe coding 的边界：它把「从零到能跑」的时间压缩到极限，但「从能跑到能上线」的每一步，依然要靠自己的判断力。

工具不会替你踩坑，只会让你踩坑的速度更快。想清楚这一点，vibe coding 就是很好的工具；想不清楚，它只是加速翻车的引擎。

OpenCode 官网：https://opencode.ai/

OpenCode GitHub 仓库：https://github.com/anomalyco/opencode

选择对应操作系统版本进行安装，具体步骤参考官方文档

2. 配置 API Key

1. 打开设置
2. 找到「提供商」，然后在提供商这里选择你拥有的对应的 API 进行连接；如果没有可以用自定义提供商，注意自定义提供商支持的是 OpenAI 兼容格式
3. 等待连接成功提示，即完成绑定就可以用了

3. 优化

3.1 安装插件

推荐安装 oh-my-openagent

GitHub 仓库：https://github.com/code-yeongyu/oh-my-openagent

复制下面的文档提示词给 AI，让 AI 安装即可（例如：「请帮我安装 oh-my-openagent」）

3.2 MCP 服务器

安装 oh-my-openagent 以后会自带几个 MCP 服务器，这边推荐几个好用的：

• playwright
• chrome-devtools
• github

4. 按需配置 oh-my-openagent agent 使用模型

探索可以启用速度快的，调研可以使用有原生搜索能力的，然后规划可以用性能强的，像审查呀那些的也推荐是性能强的，一般的写入用正常的模型即可，不需要特别强，看需求写入即可。

2 月博客上线的时候，我写过一篇 从零到一：博客搭建之旅。那篇文章讲的是「怎么把站搭起来」。

半年多过去了，我又做了 TimeMark、两款 Web 游戏、知屋阅读书房，还有 8 月初刚推出的光子遥控——一个自研 14 种红外协议编码器的安卓 App。博客本身也从 v1.0 迭代到 v2.2。如果只用一句话概括这段时间，大概是：

从「跟着教程和框架走」，慢慢变成「敢自己设计架构、敢砍过度设计、敢为真实场景做取舍、敢啃底层协议」。

这篇不是某一次升级的 changelog，而是把所有项目串成一条线的复盘。技术细节会写（而且这次附上真实代码），但更重要的是：每个项目为什么做、做错了什么、学到了什么。

时间线：六个阶段

回看 git 记录和 Changelog，这大半年大致可以分成六段：

下面按项目和阶段展开。

一、个人博客：从 v1.0 到 v2.2

博客是我所有项目的「大本营」——文章在这里发，其他项目的开发过程也在这里记录。

v1.0：先跑起来（2 月）

技术栈很早就定了：Next.js 15 + Contentlayer2 + Tailwind + Cloudflare Pages 静态导出。

选静态导出是有意为之：没有服务端，部署简单，攻击面小。评论用 Giscus（GitHub Discussions），搜索先用 kbar 匹配标题。

v1.0 解决的是「有没有」的问题。深色模式、RSS、Sitemap、基础安全头（CSP、HSTS）都在这一版落地。

那会儿我对前端几乎一无所知，是照着 mengke.me 这个开源项目一步步改造的。Fork → 换文案 → 换配色 → 加功能，就像在别人的地基上盖自己的房子。后来我才慢慢意识到，「会改别人的代码」和「会设计自己的架构」之间，隔着半年时间的距离。

v1.1–v1.2：功能补全 + 液态玻璃（4 月）

4 月是博客改动最密集的一个月之一，commit 数量能到几十条。主要方向：

交互与阅读

• 阅读进度条、增强 TOC（移动端抽屉）
• 相关文章评分算法、系列导航（上一篇/下一篇/进度）
• 键盘快捷键帮助面板、Changelog 页、友链申请表
• Service Worker 离线支持、构建期 OG 图生成

液态玻璃设计系统

全站 UI 从手写 glass 样式迁移到统一的 liquid-glass 四层体系。核心是 CSS 变量 + backdrop-filter，不依赖任何第三方库：

:root {
  --lg-blur: 20px; /* 标准层级模糊度 */
  --lg-blur-elevated: 30px; /* 导航栏 / 模态框 */
  --lg-blur-subtle: 12px; /* 次要区块 */
  --lg-saturate: 180%;
  --lg-bg: rgba(255, 255, 255, 0.45);
}

.dark {
  --lg-bg: rgba(255, 255, 255, 0.04); /* 深色模式自动切换 */
}

.liquid-glass {
  backdrop-filter: blur(var(--lg-blur)) saturate(var(--lg-saturate));
  background: var(--lg-bg);
  transition: background 0.3s ease;
}

四个层级对应不同场景：liquid-glass（卡片/列表）、liquid-glass-elevated（导航栏/模态框）、liquid-glass-subtle（次要区块）、liquid-glass-input（表单，带 focus 光晕）。深浅色模式靠 .dark 下的变量覆盖，一套 CSS 两套皮肤。

还做了滑动 Pill 导航指示器（spring easing 药丸动画），以及中文标签 404 的 Cloudflare Pages 路由兼容。

项目结构规范化

css/ → styles/，JSON 数据迁入 data/，图片目录统一为 covers/、banners/、posts/。写了 CONTENT_GUIDE.md，以后发文章有章可循。

这个月我最深的体会是：好看的 UI 不是玄学，是 CSS 变量的分层管理。把颜色、模糊度、透明度抽象成变量之后，「换皮肤」就只是改几个数字的事。

v1.3：SEO、About 与视觉（5 月初）

• AI 爬虫权限（GPTBot、ClaudeBot 等）与 llms.txt 自动生成
• About 页重设计：Profile 卡片 3D tilt、流动背景动画
• 一言（Hitokoto）迁入 Footer，30 秒自动刷新
• Moments 数据源统一为单一 moments.json

v2.0：从「能用」到「好用」（5 月底）

这是博客迄今最大的一次功能爆发，50+ 项改进、70+ 文件、9 次集中 commit。详细过程见 博客大升级 v2.0，这里只列骨架：

v2.0 的教训也很明确：不要过度工程化（曾想用本地 AI 做语义搜索，最后 Pagefind 够用）；Sandpack 在线运行代码块因加载不稳定被移除；trusted-devices.json 误提交敲了一次安全警钟。

v2.1：好维护、好审计（7 月）

高考后的暑假，博客进入「工程化」阶段——不大改 UI，而是让构建更快、边界更清晰：

构建期 Mermaid

文章里的图表在 Contentlayer 编译时用 JSDOM + Mermaid 预渲染成 SVG，亮/暗双主题各一份，DOMPurify 清理输出。读者侧零 JS 渲染、零闪烁。失败则回退客户端组件，不阻断发布。

构建并发

run-with-concurrency.ts 按 CPU 核心数限制图片优化与 OG 生成的并行度（2–6 路），避免 Promise.all 打满内存。

构建前安全自检

新增 scripts/security-audit.ts，在每次构建前自动跑一遍。核心逻辑很朴素——就是检查清单 + 正则扫描：

// scripts/security-audit.ts（节选）
const required = [
  'Content-Security-Policy',
  'Strict-Transport-Security',
  'X-Frame-Options',
  'X-Content-Type-Options',
  'Referrer-Policy',
  'Permissions-Policy',
]
for (const h of required) {
  if (headers.includes(h)) pass(h)
  else fail(`缺少 ${h}`)
}

// 扫描源码里的硬编码密钥模式
const secretPatterns = [
  /ghp_[A-Za-z0-9]{36}/, // GitHub PAT
  /sk-[A-Za-z0-9]{20,}/, // OpenAI key
  /AKIA[A-Z0-9]{16}/, // AWS key
]

检查项包括：_headers 是否含全套安全头、工作区是否存在 .env 等敏感文件、源码中是否出现密钥模式、Service Worker 是否只缓存同源 GET。有错误就 process.exit(1) 阻断构建——把「安全」从自觉变成强制。

内容与元数据

• 全文 RSS（而不只是摘要）
• schema-dts 生成类型安全的 BlogPosting JSON-LD
• remark-smartypants 排版插件

又踩过的坑

• kbar 打开搜索时导航 Pill 位移：根因是滚动条被隐藏导致布局宽度变化。最终解法是 ResizeObserver 监听容器尺寸重算指示器位置：

// components/header/index.tsx（节选）
const updateIndicator = () => {
  const active = containerRef.current?.querySelector('[data-active]')
  if (active) {
    indicator.style.width = `${active.offsetWidth}px`
    indicator.style.transform = `translateX(${active.offsetLeft}px)`
  }
}

const observer = new ResizeObserver(() => updateIndicator())
observer.observe(containerRef.current)

• Image 组件误删 overflow-hidden：Logo 和 Profile 卡片圆角变方，已恢复。

v2.2：安全加固 + 新功能（8 月初）

做完光子遥控之后，我回头给博客做了一轮「年度审计」——用 AI 帮我把整个站点的安全、依赖、性能、SEO 从头过了一遍，一次提交 55 个文件的改动。这大概是第一次用「审计」而不是「加功能」的视角来对待自己的项目：

安全加固

• 供应链 CVE 修复：通过 pnpm-workspace.yaml 的 overrides 把 postcss、sharp、picomatch、ws 强制升级到安全版本，pnpm audit --prod 高危清零
• CSP 大收紧：img-src 限制为 'self' data: blob: https:，frame-src 只保留视频平台白名单并补上 vimeo.com，新增 frame-ancestors 'none'（防点击劫持），HSTS 加 preload
• JSON-LD 里的 </script> 转义（防止标题注入破坏页面结构）
• pagefind 搜索摘要加 DOMPurify 净化（防存储型 XSS）
• Service Worker 缓存策略升级：缓存名 bump 到 v2，HTML 请求加 response.ok 校验（防缓存 404 页面）
• search.json 精简：把 filePath、structuredData 等冗余字段从输出剥离，避免暴露内部路径
• CodeQL workflow 的 GitHub Action 全部 pin 到完整 SHA（供应链安全）
• 清理 GITHUB_API_TOKEN 环境变量（已弃用）和一堆死代码

性能

• LCP 图片加 fetchpriority="high"（首页头像、文章封面提前加载）
• Giscus 评论区改为 IntersectionObserver 懒加载 + 点击按钮兜底（首屏不再加载评论 iframe）
• 文章正文加 content-visibility: auto（浏览器跳过屏外区块的渲染）
• 给实际用到的外部域名加 preconnect（giscus.app、hitokoto 等）

SEO

• OG 图升级为多尺寸（1200×630 + 1:1 方形）
• BlogPosting 结构化数据补 wordCount、inLanguage、dateModified
• About 页新增 ProfilePage JSON-LD（作者信息对搜索引擎更友好）

新功能

• Photos 照片墙页面：8 月新页面，支持 4 种媒体类型（静态照片 / Live Photo / 动图 / 视频），瀑布流 + lightbox + 长按播放，媒体直接打包进仓库
• 搜索升级：kbar 集成 fuse.js 模糊搜索，中文错字、拼音都能命中（原来只能精确匹配标题）
• 分享扩展：从 7 渠道扩到 32 平台（内嵌 17 个常用 + 更多面板 14 个）

依赖升级

14 项依赖安全升级（react 19.2.8、next 15.5.22、prettier 3.9.6 等），全部逐组升级、每步构建回归，最后 pnpm audit --prod 0 high/critical。

这次审计让我意识到：项目做久了，「维护」本身就是一种能力。不加新功能、只做减法，反而让整个站点更健康。

二、TimeMark：第一个 Docker 全栈项目

TimeMark 是智能事件提醒系统——农历生日、纪念日，多渠道通知（微信、QQ、钉钉、邮件等三十多种）。

完整开发故事见 TimeMark：我的第一个 Docker 项目。复盘里只提炼架构演进，因为这是半年里最重要的技术认知之一。

v1.x：三容器的「豪华配置」

第一版：PostgreSQL + Redis/Bull + 应用，三个容器、约 800MB 内存。

选型时觉得「专业」——正经数据库、业界标准队列。NAS 用户反馈很直接：低功耗机器上跑不动，一个提醒工具何必这么重。

v2.0：大道至简

两周重写后端：

v2.1 又给所有环境变量加了内置默认值，docker compose up -d 后零配置即用——因为家庭内网场景下，「强迫用户生成随机密钥」本身就是设计错误。还有云平台版（Vercel + PostgreSQL + Serverless），给没有 NAS 的场景用。

从 TimeMark 学到的

1. 先想清楚用户场景，再选技术——家庭用户要的是简单可靠，不是架构炫技
2. monorepo + 共享类型——前后端共用 Event 等类型定义，改一处两边生效
3. 踩坑密度高——Docker Hub 用户名改六次、镜像名拼写、GHCR 路径……都是真实发布才会遇到的问题
4. 换数据库不是换驱动——PostgreSQL → SQLite 时 TO_CHAR()、布尔值、日期排序全都不一样，SQL「标准」在不同数据库里各有怪癖
5. 通知渠道用适配器模式——35+ 渠道统一抽象成一个接口，新增渠道只写一个 adapter，这个设计让我后来做红外协议编码器时受益很大

三、Web 游戏：敢不用框架

高考前不到一个月，我用 纯 Vanilla JavaScript 做了两款游戏，零依赖、零框架。详见 从弹幕射击到经典扫雷。

星域战机（弹幕 STG）

• 纯 JS 约 11,500 行，含配置近两万行
• 20 流派 × 200 技能 × 20 武器 × 40 道具，数据驱动
• 引擎与内容分离：新流派只改 config.js，不动引擎

核心技术点：Canvas 渲染、requestAnimationFrame 游戏循环、对象池复用子弹/粒子、Web Audio API 音效。

对象池是弹幕游戏不卡顿的关键——屏幕上几百颗子弹飞，如果每颗都 new，GC 会疯掉。整个游戏运行中 new 只发生在最开始：

class ObjectPool {
  constructor(factory, initialSize) {
    this._items = []
    this._factory = factory
    for (var i = 0; i < (initialSize || 0); i++) {
      this._items.push(factory())
    }
  }
  pop() {
    return this._items.length > 0 ? this._items.pop() : this._factory()
  }
  push(obj) {
    this._items.push(obj)
  }
}

还有游戏循环的「死亡螺旋」——切标签页再切回来，浏览器暂停了 requestAnimationFrame，回来时 deltaTime 飙到几秒，所有物体瞬间飞出屏幕。解法是一行 Math.min(rawDt, 50)，超过 50ms 的帧一律按 50ms 算：游戏可能短暂变慢，但不会崩。

经典扫雷

• 像素级还原 Windows XP/7 扫雷
• BFS 洪水填充展开空白区、无尽模式、成就、PWA 离线
• 三天完成，验证「小项目也能打磨细节」

为什么做游戏

博客和 TimeMark 都站在框架肩膀上。我想证明：不依赖 React/Next，也能做复杂交互。 对象池、BFS、状态机——这些在框架里常被封装，自己写一遍才真正理解。后来做光子遥控的红外协议编码器时，这种「从底层自己造」的感觉又回来了——原来框架和库帮你藏起来的细节，才是真正值钱的知识。

四、知屋：从阅读器到 1.0 书房

知屋是私人阅读与笔记项目，和博客的静态架构完全不同：

静态页面（Astro） + Serverless API（Hono） + Redis 会话 + 对象存储 + Git LFS 书库

博客是「写出来给人看」；知屋是「用起来管自己的书与笔记」。闭源、需登录，不对外公开仓库与部署地址。

7 月集中迭代做了什么

阅读与内容

• EPUB/PDF 阅读、划线批注、三栏布局阅读器
• 从 PagePulse 迁移教材目录、FSRS 间隔复习、闪卡与词汇
• 书架按章节正文含量自动分级（书籍 vs 学习资料）
• 内置教材封面本地化、章节纲要逐节正文

AI

• 从本机 ONNX 逐步迁到云端流式代理（用户 Key 加密存 Redis，不进部署环境变量）
• 多会话对话 UI、停止/重试、提示词缓存
• 后期精简 Agent 提示词与权限边界

存储

• Vercel Blob → Cloudflare R2 优先，统一 cloud-store 抽象层——换存储厂商只改一个实现，上层代码不动
• 私有书库 Vault（Git LFS）存 PDF/笔记/进度，与前端代码仓分离，无公开 raw 链接

安全（三轮加固）

• localStorage 会话 → HttpOnly Cookie
• 人机验证（Turnstile）、CORS 绑定正式域名
• 本地 security-probe 自检脚本
• 修复登录重复弹窗、OpenList 兼容性等

客户端

• Android / Windows 原生壳（加载线上站点，WebView 行为与浏览器一致）

知屋让我第一次系统面对有用户数据的后端安全：静态博客扫一遍 _headers 就够；全栈项目要管会话、存储、AI Key、跨域、探针，完全是另一个量级。三轮 fix(security) 才稳住，每一轮都是被真实问题（或者说，被「万一被别人搞」的想象）逼出来的。

五、光子遥控：第一个原生 Android 项目

完整代码：github.com/WXFffff666/photon-remote

这是 8 月初刚推出的项目，也是我的第一个原生 Android 应用——之前的所有项目都在 Web 技术栈里打转。

为什么做

家里遥控器太多了：电视一个、机顶盒一个、空调一个、风扇一个，每个都长得差不多，还总找不到。市面上万能遥控 App 不少，但要么广告满天飞，要么机顶盒运营商码库不全。于是决定自己写一个。

光子遥控是一款安卓万能红外遥控器：把电视、机顶盒、空调、风扇等家电装进手机里，中国国内市场优先，完全离线可用。

技术栈

14 种红外协议编码器

红外遥控最底层的知识：每种协议定义了载波频率、前导码、位时序。比如最经典的 NEC 协议——38kHz 载波，前导 9000/4500 µs，逻辑 0 是 562/562 µs，逻辑 1 是 562/1687 µs，每字节 LSB 先发。

我把这 14 种协议（NEC 家族 / RC5 / RC6 / SONY / SAMSUNG / SHARP / JVC / KASEIKYO / PIONEER / RAW）全部自研实现，每个协议一个文件，接口统一：

// ir/core/ProtocolType.kt
enum class ProtocolType {
    NEC, NECX1, NECX2, RC5, RC6, SONY12, SONY15, SONY20,
    SAMSUNG32, SHARP, JVC, KASEIKYO, PIONEER, RAW
}

以 NEC 编码器为例——输入一个 hex 码串，输出一串 mark/space 时间间隔（微秒）：

// ir/protocol/NecEncoder.kt（节选）
object NecEncoder : IrProtocolEncoder {
    override val protocol: ProtocolType = ProtocolType.NEC
    override val repeatIntervalMs: Int = 110   // NEC 长按重复间隔

    const val FREQUENCY = 38000                // 38kHz 载波
    const val PRE_MARK = 9000                  // 前导 mark µs
    const val PRE_SPACE = 4500                 // 前导 space µs
    const val BIT_MARK = 562                   // 位 mark
    const val BIT0_SPACE = 562                 // 逻辑 0 的 space
    const val BIT1_SPACE = 1687                // 逻辑 1 的 space

    override fun encode(hex: String, press: PressKind): IRPattern {
        if (press == PressKind.REPEAT) {
            // NEC 短重复帧：9000/2250 + 562µs mark，与码值无关
            return IRPattern(FREQUENCY, intArrayOf(PRE_MARK, 2250, 562))
        }
        val normalized = hex.trim().uppercase().padStart(8, '0')
        require(normalized.length <= 8) { "NEC 码最多 8 位十六进制: $hex" }

        // 每字节 LSB 先发：0x00FF12ED → 4 字节，每字节低位在前
        val bytes = normalized.chunked(2).map { it.toInt(16) }
        val bits = bytes.flatMap { b -> (0..7).map { (b shr it) and 1 } }

        val list = mutableListOf<Int>()
        list += PRE_MARK; list += PRE_SPACE
        for (b in bits) {
            list += BIT_MARK
            list += if (b == 0) BIT0_SPACE else BIT1_SPACE
        }
        list += 562                                  // 帧尾
        list += (108_800 - list.sum()).coerceAtLeast(0)  // 补零到整帧
        return IRPattern(FREQUENCY, list.toIntArray())
    }
}

这段代码看起来简单，但每个数字背后都是真实硬件的行为约束：ConsumerIrManager.transmit 会阻塞到整帧发完（NEC 补零后最长 108.8ms），所以绝不能在主线程调用；长按重复帧必须和完整帧区分开，否则长按音量键会卡死界面。

单线程发射调度器

宏、暴力找码、长按连发可能同时触发发送，而 IREXT 的 JNI 解码是共享原生状态的单例——并发调用会互相污染。所以所有红外发送和 IREXT 解码都走一个单线程队列：

// ir/transmitter/IrDispatcher.kt（节选）
class IrDispatcher(
    private val transmitFn: suspend (IRPattern) -> Boolean,
    private val scope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.Default),
) {
    private val queue = Channel<suspend () -> Unit>(Channel.UNLIMITED)

    init {
        scope.launch { for (task in queue) task() }   // 常驻消费协程，天然串行
    }

    suspend fun send(pattern: IRPattern): Boolean =
        onQueue { transmitFn(pattern) }

    suspend fun <T> onQueue(block: suspend () -> T): T {
        val deferred = CompletableDeferred<T>()
        queue.send { deferred.completeWith(runCatching { block() }) }
        return deferred.await()
    }
}

原理很简单：一个 Channel 队列 + 一个常驻消费协程，所有任务进去后逐个执行，天然串行。CompletableDeferred 让调用方能拿到结果，runCatching 保证某个任务炸了不影响队列后续任务。

机顶盒省市运营商三级筛选 + 离线码库

中国市场的机顶盒码库按「省份 → 城市 → 运营商（移动/联通/电信/广电）」组织，再结合定位自动匹配。码库来自 IREXT 的开源实现（MIT 协议，JNI 离线解码二进制码库），加上精选的 irdb CSV，完全离线内置，飞行模式下也能用。

其他亮点

• 宏：把多个设备的多步按键串成一条宏（如「电视开机 → 调音量 → 机顶盒确定」），可调步间延迟、可中途停止
• 暴力找码：协议 + hex 前缀约束，自动迭代发码，设备一响应就保存为按键
• 导入导出：Flipper .ir、LIRC .conf、JSON 全量备份，逐条校验，坏记录跳过不中断
• 无红外扩展：USB 红外外设（RLE 帧收发、热插拔重连）和音频转红外适配器（AudioTrack 192kHz 合成 38kHz 载波）
• 211 个单元测试：协议波形（前导/位序/帧尾/总长）、数据层、调度器、序列化全覆盖

从光子遥控学到的

1. 「简单」的底层往往最难——一个 NEC 编码器 40 行，但它是被真实硬件约束逼出来的：阻塞时长、重复帧、补零，全是查协议文档 + 实机测试得来的
2. 共享原生状态要串行化——JNI 单例 + 并发调用 = 状态污染，一个 Channel 队列解决
3. 测试先行在协议层最值钱——波形是纯函数，输入输出确定，211 个单测里协议测试占了很大比重，改起来心里有底
4. 国产市场的坑——运营商机顶盒码库、省市筛选、定位匹配，这些「本地化」需求是海外开源项目永远不会替你考虑的

六、其他项目（简表）

这些在博客 Projects 页有卡片展示；闭源项目只写能力描述，不附仓库或线上链接。

顺带说一句：上面提到的「给设备编译驱动」，是给自己的设备编译适配——比如给我的小米平板编一个能用的 GPU 驱动模块，配合 Magisk 刷进去用。这不是从零编译完整驱动（我也没那个能力），而是在开源驱动源码基础上做配置、打补丁、适配到我的设备上。折腾设备这件事，本来就不是「从零造轮子」，而是把别人造好的轮子装到自己车上，并且让它转起来。

七、横向对比：我怎么做技术选型

半年里五个主项目，架构差异很大，但选型逻辑有迹可循：

一个越来越清晰的原则：用户是谁、数据存在哪、要不要登录——三个问题先答了，技术栈就不会偏太远。到了光子遥控，答案变成了：要不要碰硬件、要不要离线——要，那就原生 + 本地库 + 离线码库，别想用 Web 壳糊弄。

八、安全：三种完全不同的工作量

静态博客

攻击面主要是 XSS（MDX、Giscus）、供应链依赖、CSP 配置。v2.1 加了构建前 security-audit.ts（代码见上文），v2.2 又做了一轮完整加固（CVE overrides、CSP 收紧、JSON-LD 转义、DOMPurify、sw.js 缓存策略），检查项包括：

• _headers 是否含 CSP、HSTS、X-Frame-Options 等
• 工作区是否存在 .env、误提交的敏感文件
• 源码中是否出现 ghp_、sk- 等密钥模式
• Service Worker 是否只缓存同源 GET
• pnpm audit --prod 是否 0 high

已知权衡：Next.js 静态导出需要 CSP unsafe-inline；img-src * 方便文章外链图——都是可接受的残余风险。

全栈应用（知屋）

HttpOnly Cookie、Turnstile、CORS 收紧、AI Key 加密、R2 权限、安全探针脚本……三轮 fix(security) 才稳住。有后端就必须按后端的标准做，不能套用静态站的检查清单。

原生 App（光子遥控）

又是另一种维度：开源协议合规。App 内置了 IREXT（MIT）、irdb（宽松许可）、Flipper IRDB（MIT）三套第三方码库，README 里逐一声明出处；明确排除了 AGPLv3 的 mi_remote_database——选型时就把许可不兼容的库挡在门外，比事后换库便宜得多。

九、踩坑合集（跨项目）

把各项目里印象最深的坑放在一起，方便以后翻：

1. 过度设计 — TimeMark v1 三容器；博客曾想用本地 AI 搜索。解法：先 MVP，再按需加。
2. 像素级 UI bug — kbar 位移、圆角被 overflow-hidden 误删。解法：模态框 + 居中布局要测滚动条；改 UI 组件要看回归。
3. 发布细节 — Docker 镜像名拼错、Hub 用户名多次调整。解法：CI 里固定镜像名，文档写清推送步骤。
4. 静态站 CSP — 想要严格 nonce，但没有服务端。解法：接受 unsafe-inline 或维护 hash 列表（成本高）。
5. 死代码拖延 — Sandpack 移除 Run 按钮后依赖留了几个月。解法：功能砍掉就删依赖，别「以后可能还用」。
6. 安全文件误提交 — trusted-devices.json。解法：.gitignore + 构建前扫描。
7. JNI 状态污染 — 光子遥控的 IREXT 是共享原生单例，并发解码会互相污染。解法：所有解码走单线程队列（IrDispatcher）。
8. 阻塞型硬件调用 — ConsumerIrManager.transmit 会阻塞到整帧发完（最长 108.8ms）。解法：绝不在主线程调用，统一走后端调度器。
9. 供应链漏洞 — 传递依赖（postcss、sharp 等）有 CVE。解法：pnpm overrides 强制升级，audit 常态化。
10. 缓存了 404 — sw.js 缓存了失败响应，离线时页面错乱。解法：缓存前检查 response.ok。

十、数据印象（不追求精确）

博客 Changelog 从 v1.0.0 记到 v2.2.0，光 5 月底 v2.0 单次升级就 50+ 项改进——这些数字说明的是迭代频率，不是炫耀代码行数。

十一、如果重来，我会怎么排期

诚实说，有些顺序我会调整：

1. 博客 v2.0 可以拆成两期 — MDX 组件 + Pagefind 一期，分享/动画一期，避免一次改太多难以回归测试。
2. TimeMark 应该更早做单容器 — v1 的三容器架构本可跳过，直接听 NAS 用户场景。
3. 知屋 AI 路径应更早定云端 — 本机 ONNX 在 Vercel 构建体积和 Edge 跟踪防护下走了很多弯路，最后仍迁到服务端代理。
4. 文档与博客同步写 — TimeMark 和游戏的专文是事后补的；边做边写能少靠 git 回忆决策原因。
5. 安全审计应该定期做，而不是等大版本 — v2.2 的 55 文件大改动如果拆成每月一次的小审计，风险会更小。

反过来，不会改的选择：博客坚持静态导出、游戏坚持 Vanilla JS、TimeMark v2 砍 Redis/Postgres、知屋闭源且数据与代码分仓、光子遥控坚持自研协议编码器（而不是直接套现成库）——自己把 NEC 波形写一遍，才知道那些开源库帮你藏了多少细节。

十二、下半年想做什么

不列具体地址，只列方向：

• 博客：继续写文章，CSP 与依赖审计常态化，少堆新功能、多打磨阅读体验
• 知屋：1.0 后的文档与复习闭环，存储配额与 LFS 策略长期可维护
• TimeMark：跟用户反馈迭代通知渠道与部署体验
• 游戏：高考后若有空，给扫雷加更多主题或给 STG 做平衡性调参
• 光子遥控：继续补全 UI 细节与更多设备码组，把离线码库的维护流程跑通
• 折腾设备：继续给我的设备编译适配驱动模块、玩 NAS，把「折腾」写进博客

总结

这半年多，我不是在「学一门技术」，而是在反复经历同一条曲线：

做一个东西 → 觉得不够好用或大改 → 踩坑 → 写文档或博文 → 下一个项目带着上次的教训

博客教会我前端工程化和设计系统；TimeMark 教会我别为用技术而用技术；游戏教会我框架之下还有什么；知屋教会我有数据就要有安全模型；光子遥控教会我最底层的协议里藏着最硬的知识——以及，选型时要先把开源协议的许可看清楚。

如果你也在读书、做作业之余做 side project，我的建议只有一句：做给自己用的东西，然后把踩坑写下来。 半年后回头看，会比只记得「做过某某项目」有用得多。

更多分项细节可参阅本系列其它文章：博客搭建之旅、博客 v2.0 升级、TimeMark Docker、Web 游戏开发手记，以及站内 Changelog。

距离上次写博客搭建文章已经过了几个月了。这段时间里，我一直在用这个博客写文章、记录生活，但总觉得少了点什么——功能太单调了，读者体验也不够好。

于是趁着周末，我决定给博客来一次大升级。没想到这一改就停不下来了，最后做了 50+ 项改进，涉及 70+ 个文件，提交了 9 次 commit。

这篇文章记录一下这次升级的过程，包括做了什么、怎么做的、踩了哪些坑。

为什么要升级

说实话，之前的博客虽然能用，但有几个问题一直困扰我：

1. 功能单调 — 除了写文章和评论，没有其他互动方式
2. 搜索不够好 — kbar 搜索只能匹配标题，不能搜文章内容
3. 分享不方便 — 想分享给朋友，只有几个国外平台的按钮
4. 阅读体验一般 — 字体大小固定，没有专注模式
5. MDX 组件太少 — 写技术文章时想用 Tabs、Steps 这些组件，但没有
6. 有几个 Bug — 图片放大不了、一言不刷新、有测试数据残留

所以这次的目标很明确：让博客从"能用"变成"好用"。

这次做了什么

🐛 Bug 修复（4 项）

• 修复了 trusted-devices.json 被意外提交到 Git 的安全问题
• 实现了一言（Hitokoto）30 秒自动刷新 + 淡入淡出动画
• 清理了 Moments 里的测试数据
• 移除了代码块的 Run 按钮（Sandpack 加载太不稳定了）

📦 MDX 组件库（15 个新组件）

这是这次升级最大的工作量。我一口气做了 15 个 MDX 组件：

🔍 Pagefind 全文搜索

这是我最满意的功能之一。Pagefind 在构建时自动索引所有文章内容，支持中文分词，搜索速度极快。

📖 阅读体验增强（6 项）

• 字体大小控制（S/M/L 三档）
• 专注阅读模式（隐藏所有干扰）
• 阅读位置记忆（下次打开恢复位置）
• 文章语音朗读（Web Speech API）
• 文章难度标签
• 归档时间线页面

🔗 社交分享（7 渠道）

微信（二维码）、QQ、微博、X、Telegram、Reddit、复制链接。移动端优先使用系统原生分享。

🎨 视觉与动画

• 页面切换动画（View Transitions API）
• 终端风格 404 页面（打字机效果）
• 暗色模式切换动画（圆形扩散）

📱 移动端优化

• 左右滑动切换文章
• PWA 安装提示
• 下拉刷新动画

🔧 其他改进（15+ 项）

键盘导航 J/K、拼音搜索、KaTeX 公式复制、Mermaid 图表放大、TOC 折叠记忆、文章卡片入场动画、代码块增强（行号/文件名）等等。

技术亮点

Pagefind 全文搜索

Pagefind 的集成非常简单。只需要在 postbuild 脚本中加一行：

npx pagefind --site out --glob "**/*.html"

它会自动扫描所有 HTML 页面，生成搜索索引。在文章内容区域加上 data-pagefind-body 属性，就能精确控制索引范围：

<div className="prose" data-pagefind-body>
  {children}
</div>

搜索结果支持中文分词，虽然不支持词干提取（stemming），但对于博客搜索来说完全够用了。

MDX 组件示例

有了这些组件，写技术文章方便多了。比如：

<Callout type="tip" title="小贴士">
  使用 `pnpm` 比 `npm` 快很多，而且节省磁盘空间。
</Callout>

<Tabs items={['pnpm', 'npm', 'yarn']}>
  <Tab value="pnpm">pnpm install next</Tab>
  <Tab value="npm">npm install next</Tab>
  <Tab value="yarn">yarn add next</Tab>
</Tabs>

<Steps>
  <Step title="安装依赖">运行 pnpm install</Step>
  <Step title="启动开发">运行 pnpm dev</Step>
  <Step title="构建部署">运行 pnpm build</Step>
</Steps>

液态玻璃设计统一

这次把所有组件都统一到了液态玻璃设计系统。四个层级：

• liquid-glass — 标准卡片
• liquid-glass-elevated — 弹出层/模态框
• liquid-glass-subtle — 次要元素
• liquid-glass-input — 表单输入

所有新组件都遵循这个规范，确保视觉一致性。

View Transitions 页面动画

利用浏览器原生的 View Transitions API，实现了页面切换时的平滑过渡。不支持的浏览器会自动降级为普通跳转，不影响功能。

遇到的坑

1. Cloudflare Pages 不支持原生模块

一开始我想用 @xenova/transformers 在构建时跑本地 AI 模型来做语义搜索。结果发现 CF Pages 的构建环境不支持 onnxruntime-node（原生 C++ 模块）。

最后放弃了 AI 方案，改用 Pagefind + 标签权重算法。对于我目前不到 10 篇文章的规模，效果其实差不多。

2. Sandpack 加载不稳定

代码块的"Run"按钮用的是 CodeSandbox 的 Sandpack，但不管开不开加速器都经常加载失败，一直转圈。最后决定直接移除这个功能。

3. overflow-hidden 阻止图片缩放

react-medium-image-zoom 的放大效果被父容器的 overflow-hidden 给裁剪了。解决方法很简单——把 overflow-hidden 去掉就行。

4. Safari 隐私模式 localStorage 报错

Safari 的隐私浏览模式下，localStorage.setItem() 会直接抛异常。所有用到 localStorage 的地方都需要 try/catch 包裹。

数据统计

下一步

• 📝 继续写文章，记录学习和生活
• 🎓 准备高考（这才是正事！）
• 🔧 根据实际使用情况继续打磨细节
• 📊 观察 Pagefind 搜索的实际效果

总结

做博客就像种花——你不能指望种下去第二天就开花，需要持续浇水、施肥、修剪。每次升级都是一次"施肥"，让博客变得更好一点。

这次 v2.0 升级让我学到了很多：

• 不要过度工程化 — 一开始想用 AI 模型，后来发现简单算法就够用
• 用户体验很重要 — 小细节（如字体控制、位置记忆）能大幅提升阅读感受
• 保持一致性 — 液态玻璃设计系统让所有组件看起来是一个整体
• 渐进增强 — 新功能不支持就降级，不影响基本使用

好了，该去复习了。高考加油！💪

距离高考还有不到一个月。

按理说这个时候应该全力冲刺，但说实话，连续刷了几个月的题，脑子有时候真的转不动了。晚自习回来，打开电脑，本来想看看数学错题，结果手不自觉地打开了 VS Code。这种感觉做过博客和 TimeMark 的人应该懂：一旦你习惯了创造东西，就很难停下来。

做游戏这个念头其实很早就有了。小时候在学校机房玩 4399 上的 Flash 小游戏，那时候就想：这些东西是怎么做出来的？后来学了 JavaScript，发现浏览器本身就是一个游戏引擎。Canvas 能画任何东西，requestAnimationFrame 能跑 60 帧。不需要 Unity，不需要 Godot，一个浏览器就够了。

还有一个原因。做完博客和 TimeMark 之后，我一直在用框架。Next.js、React、Hono……框架确实好用，但我想证明一件事：纯 Vanilla JavaScript，不依赖任何框架和库，也能做出复杂的东西。 博客是站在巨人肩膀上，TimeMark 是全栈但有框架兜底，这次我想从零开始，自己造所有轮子。

于是就有了这两个项目。一个大的，一个小的。一个花了两周，一个花了三天。

星域战机：一万一千行的弹幕射击

它是什么

星域战机是一个 HTML5 Canvas 弹幕射击游戏（STG）。无尽模式，越打越难，死了重来。

听起来简单对吧？但内容量比我预想的大得多。最终纯 JavaScript 部分大约一万一千多行，算上 HTML 和 CSS 接近两万行。

规模有多大？看数据：

• 20 个流派（相当于角色 build）
• 200 个技能（每次升级随机三选一）
• 20 种武器
• 40 个道具
• 16+ 种敌人
• 4 个 Boss

这些内容全部是数据驱动的，后面会详细说。

🎮 在线试玩：game1.the37777777.top/ulw

📦 源码：github.com/WXFffff666/stg-game

数据驱动架构：引擎和内容完全分离

这个项目最让我满意的设计决策是：引擎只负责执行逻辑，所有内容定义在配置文件里。

想加一个新流派？往 config.js 里加一条数据就行，引擎代码一行都不用改。来看看实际的流派配置长什么样：

FACTIONS: {
  attackSpeed: {
    id: 'attackSpeed', name: '⚡ 攻速流', color: '#ffdd00',
    description: '极致射速，弹幕如雨',
    baseStats: { attackSpeed: 0.4, attack: 0.85, hp: 100, speed: 300, critRate: 0.05, critMult: 1.5, bulletCount: 0 },
    icon: '⚡'
  },
  counter: {
    id: 'counter', name: '🛡️ 反伤流', color: '#ff6644',
    description: '挨打反弹，以守为攻',
    baseStats: { attackSpeed: 1.0, attack: 0.9, hp: 150, speed: 260, reflectDamage: 0.3, defense: 0.2, critRate: 0.05, critMult: 1.5 },
    icon: '🛡️'
  },
  crit: {
    id: 'crit', name: '💥 暴击流', color: '#ff0000',
    description: '一击必杀，刀刀暴击',
    baseStats: { attackSpeed: 1.0, attack: 1.2, hp: 90, speed: 290, critRate: 0.25, critMult: 3.0, critDamage: 0 },
    icon: '💥'
  },
  // ... 17 more factions
}

20 个流派，每个都是这样一条配置。攻速流射速快但攻击力低，反伤流血厚能反弹伤害，暴击流脆皮但爆发高。引擎不关心具体有多少流派，它只读取 baseStats 然后计算。

技能也是同样的思路。每个技能就是一个纯数据对象：

{ id: 'atk_up_1', name: '攻击提升 I', faction: 'any', type: 'passive', rarity: 'common',
  effects: [{ stat: 'attack', op: 'multiply', value: 0.15 }] },
{ id: 'bullet_plus_1', name: '弹道+1', faction: 'any', type: 'passive', rarity: 'uncommon',
  effects: [{ stat: 'bulletCount', op: 'add', value: 1 }] },
{ id: 'crit_up_2', name: '暴击率提升 II', faction: 'any', type: 'passive', rarity: 'uncommon',
  effects: [{ stat: 'critRate', op: 'add', value: 0.15 }] },

看到没？effects 数组里定义了这个技能修改哪个属性、用什么运算、改多少。引擎只需要遍历 effects，根据 op 字段做加法或乘法就行。200 个技能，引擎处理逻辑就那么几行，剩下的全是数据。

这种架构的好处是：加内容的速度极快。 一旦引擎稳定了，后面就是纯粹的内容创作。我后期加技能的速度大概是一小时 5、6 个，因为不需要碰引擎代码。

每个流派还有自己的终极技能，定义在 skills.js 里：

var FACTION_SYSTEM = {
  attackSpeed: {
    corePassive: { effects: [{ stat: 'attackSpeed', op: 'multiply', value: -0.15 }, { stat: 'attack', op: 'multiply', value: 0.1 }] },
    exclusiveSkills: ['as_dual_wield', 'as_frenzy', 'as_machine_gun'],
    ultimate: { id: 'ut_attackSpeed', name: '⚡ 弹幕终结', faction: 'attackSpeed', type: 'passive', rarity: 'legendary', ultimate: true,
      description: '极致攻速的终极形态',
      effects: [{ stat: 'attackSpeed', op: 'multiply', value: -0.5 }, { stat: 'ricochet', op: 'add', value: 3 }],
      visualColor: '#ffdd00', visualType: 'lightning' }
  },
  // ...
};

攻速流的终极技能「弹幕终结」：攻速再乘以 -0.5（注意这里 attackSpeed 的值越小射速越快），子弹还能弹射 3 次。配合前面基础属性里 attackSpeed: 0.4 的底子，这个流派到后期就是满屏子弹乱飞。

对象池：零 GC 压力

弹幕射击游戏最大的性能瓶颈是什么？垃圾回收（GC）。

想象一下：屏幕上同时有几百颗子弹在飞，每颗子弹飞出屏幕就销毁，新子弹不断创建。如果每颗子弹都 new Bullet()，GC 会疯掉，游戏会卡顿。

我写了一个通用的对象池类来解决这个问题：

class ObjectPool {
  constructor(factory, initialSize) {
    this._items = [];
    this._factory = factory;
    for (var i = 0; i < (initialSize || 0); i++) {
      this._items.push(factory());
    }
  }

  get length() { return this._items.length; }

  pop() {
    if (this._items.length > 0) {
      return this._items.pop();
    }
    return this._factory();
  }

  push(obj) {
    this._items.push(obj);
  }
}

原理很简单：构造的时候传入一个工厂函数和初始大小，预先创建一批对象放进池子。需要新对象的时候调 pop()，池子里有就直接拿，没有才用工厂函数创建新的。对象「死亡」后调 push() 放回池子。整个游戏运行过程中，new 操作只在最开始发生几次，之后全部是复用。

子弹、粒子、敌人、伤害数字……所有频繁创建销毁的对象都用了对象池。实测下来，即使屏幕上有 300+ 子弹同时飞行，帧率也能稳定在 60fps。

踩坑：游戏循环与 Spiral of Death

游戏的心跳是 requestAnimationFrame + deltaTime。但这里有个坑，我一开始没注意到，后来被坑了一整个晚上。

先看最终的代码：

// Inside Game class _loop method:
const rawDt = timestamp - this.lastTime;
this.lastTime = timestamp;

// Cap delta time to prevent spiral of death
const dt = Math.min(rawDt, 50) * 0.001 * this.timeScale;

if (!this.isPaused) {
  this.gameTime += rawDt;
  this._update(dt);
}

this._draw();
this.rafId = requestAnimationFrame(this._loop);

看到那行 Math.min(rawDt, 50) 了吗？这是为了防止所谓的「spiral of death」（死亡螺旋）。

什么意思呢？假设某一帧因为 GC 或者其他原因卡了 500ms，如果不做限制，deltaTime 就是 0.5 秒。这一帧里所有物体都会移动半秒的距离，子弹可能直接穿过敌人，碰撞检测全部失效。更糟糕的是，这一帧要处理的计算量暴增，导致下一帧也卡，deltaTime 更大，计算量更多……恶性循环，游戏直接崩掉。

解决方案就是给 deltaTime 加个上限。超过 50ms（相当于 20fps 以下）的帧，一律按 50ms 算。游戏可能会短暂变慢，但不会崩。

这个 bug 的现象是：切到其他标签页再切回来，游戏里所有东西瞬间飞出屏幕。当时我完全懵了，以为是碰撞检测的问题，排查了半天。后来才想明白，浏览器在后台标签页会暂停 requestAnimationFrame，切回来的时候 deltaTime 直接飙到几秒。加了这个 cap 之后就好了。

注释里写的 "prevent spiral of death" 就是那天晚上加的，算是给自己留个纪念。

程序化音效：零音频文件

整个游戏没有一个音频文件。所有音效都是用 Web Audio API 实时合成的：

// Shoot sound: short square wave decay
playShoot() {
  this._playTone('square', 800, 400, 0.05, 0.08);
}

// Explosion: noise burst with lowpass filter
playExplosion() {
  this._playNoise(0.2, 0.12, 1000);
}

// Core tone generator
_playTone(type, startFreq, endFreq, duration, vol) {
  this._ensureContext();
  if (this._muted) return;
  const ctx = this._ctx;
  const now = ctx.currentTime;

  const osc = ctx.createOscillator();
  const gain = ctx.createGain();
  osc.type = type;
  osc.frequency.setValueAtTime(Math.max(startFreq, 0.01), now);
  osc.frequency.exponentialRampToValueAtTime(Math.max(endFreq, 0.01), now + duration);
  gain.gain.setValueAtTime(vol, now);
  gain.gain.exponentialRampToValueAtTime(0.001, now + duration);
  osc.connect(gain);
  gain.connect(this._masterGain);
  osc.start(now);
  osc.stop(now + duration + 0.01);
}

射击声是一段 800Hz 到 400Hz 的方波快速衰减，持续 0.05 秒。爆炸声是白噪声加 1000Hz 低通滤波器。升级音效是两个正弦波的快速上行。听起来很 retro，但和像素风的画面很搭。

好处是显而易见的：零网络请求，零加载时间，包体积极小。坏处是调音效全靠耳朵，没有可视化工具，改一个参数就要重新听一遍。playShoot 那个 0.05 秒的持续时间我调了十几次才觉得「对味」。0.03 太短听不清，0.08 又太拖沓，最后定在 0.05。

还有个坑：exponentialRampToValueAtTime 不能 ramp 到 0，只能 ramp 到一个接近 0 的值（我用的 0.001）。一开始写的是 ramp 到 0，浏览器直接报错，查了半天 MDN 才发现这个限制。指数衰减嘛，数学上不可能到 0，想想也合理。

最大的挑战：200 个技能的平衡性

200 个技能，怎么保证不会出现某个组合过于逆天？

说实话，保证不了。😅

我的做法是分层：技能分 common、uncommon、rare、legendary 四个稀有度，高稀有度出现概率低。同一流派的技能之间有协同效果，但不同流派混搭也不会太弱。然后就是大量的自己试玩，发现太强的就削一刀，太弱的就加强。

比如攻速流一开始太强了。基础 attackSpeed: 0.4 加上终极技能再乘 -0.5，配合「弹道+1」技能多发子弹，屏幕上全是子弹，Boss 秒融。后来我把终极技能的弹射次数从 5 降到 3，才算平衡了一点。

这个过程其实挺像做数学题的：调参数、验证、再调。只不过验证的方式是打一局游戏而不是算一道题。

经典扫雷：三天的像素级还原

它是什么

做完星域战机之后，我想做个小的项目换换脑子。扫雷是我小时候在 Windows XP 上玩得最多的游戏之一，规则简单，但实现起来有不少细节。

目标很明确：像素级还原 Windows XP/7 的扫雷体验。 不是「类似扫雷」，是打开之后让人觉得「这就是那个扫雷」。

最终成品大约 2800 行代码，支持 PWA 离线游玩。

🎮 在线试玩：game2.the37777777.top

📦 源码：github.com/WXFffff666/minesweeper

功能清单

别看扫雷「简单」，要做到完整还是有不少东西的：

• 3D 凸起/凹陷边框（经典 Windows 风格）
• LED 数字计数器（剩余雷数 + 计时器）
• 左右键同时按的 chord click（双击翻开周围）
• 第一次点击保证安全（不会踩雷）
• BFS 洪水填充（点到空白区域自动展开）
• 无尽模式（通关后自动开下一局）
• 12 个成就
• 3 套主题（经典、暗色、现代）
• 统计数据和排行榜
• PWA 离线支持

模块模式架构

扫雷的代码结构比星域战机清晰得多（毕竟规模小很多）。我用了 IIFE 模块模式，把逻辑拆成独立模块。来看看渲染模块的实际代码：

MS.Renderer = (function() {
    'use strict';

    var boardEl = document.querySelector('.board');
    var mineCounterEl = document.querySelector('.mine-counter');
    var timerEl = document.querySelector('.timer');
    var smileyBtn = document.querySelector('.smiley-btn');
    var currentCols = 0;

    function createBoard(rows, cols) {
        currentCols = cols;
        boardEl.innerHTML = '';
        boardEl.style.setProperty('--cols', cols);

        var fragment = document.createDocumentFragment();
        for (var r = 0; r < rows; r++) {
            for (var c = 0; c < cols; c++) {
                var cell = document.createElement('div');
                cell.className = 'cell';
                cell.dataset.row = r;
                cell.dataset.col = c;
                fragment.appendChild(cell);
            }
        }
        boardEl.appendChild(fragment);
    }

    // ... more methods ...

    return { createBoard: createBoard, updateCell: updateCell, ... };
})();

每个模块是一个 IIFE，内部变量完全私有，只通过 return 暴露公共接口。MS.Engine 负责游戏逻辑，MS.Renderer 负责渲染，MS.Input 负责输入处理，MS.Audio 负责音效，MS.Stats 负责统计和成就。

纯逻辑和渲染完全分离。MS.Engine 不知道自己被画在哪里，MS.Renderer 不关心游戏规则。如果以后想换一套 UI（比如从 DOM 换成 Canvas），只需要重写 MS.Renderer，其他模块一行不动。

注意 createBoard 里用了 document.createDocumentFragment()。如果直接在循环里 appendChild 到 DOM，每次都会触发重排。用 fragment 先在内存里拼好，最后一次性插入，性能差距在大棋盘（30x16 = 480 个格子）上很明显。

BFS 洪水填充

扫雷里点到一个周围没有雷的空白格子，会自动展开一大片区域。这个功能的实现是经典的 BFS（广度优先搜索）。来看实际代码：

function floodFill(startRow, startCol) {
    var queue = [];
    var revealed = [];

    queue.push({ row: startRow, col: startCol });

    while (queue.length > 0) {
        var cell = queue.shift();
        var r = cell.row;
        var c = cell.col;
        var boardCell = board[r][c];

        if (boardCell.revealed || boardCell.flagged) continue;

        boardCell.revealed = true;
        revealedCount++;
        revealed.push({ row: r, col: c });

        if (boardCell.adjacentMines === 0) {
            var neighbors = getNeighbors(r, c);
            for (var i = 0; i < neighbors.length; i++) {
                var nr = neighbors[i].row;
                var nc = neighbors[i].col;
                if (!board[nr][nc].revealed && !board[nr][nc].flagged) {
                    queue.push({ row: nr, col: nc });
                }
            }
        }
    }

    return revealed;
}

为什么用迭代 BFS 而不是递归 DFS？因为大棋盘（比如 30x16）上，递归深度可能超过浏览器的调用栈限制，直接 stack overflow。迭代版本用一个队列，不管棋盘多大都不会爆栈。

注意这里的逻辑：只有 adjacentMines === 0 的格子才会继续扩展邻居。如果一个格子周围有雷（数字不为 0），它会被翻开但不会继续往外扩。这就是为什么 BFS 展开后边缘总是一圈数字。

函数返回所有被翻开的格子坐标，渲染模块拿到这个数组后批量更新 DOM。逻辑和渲染分离的好处在这里就体现出来了。

这也是算法课上学的东西第一次在实际项目里派上用场。真的挺有成就感的。

踩坑：第一次点击保证安全

扫雷有个规则很多人不知道：第一次点击永远不会踩雷。Windows 原版就是这样的。

实现方式是：雷不是游戏开始时就放好的，而是第一次点击之后才放。 放雷的时候排除掉点击位置周围 3x3 的区域：

function placeMines(safeRow, safeCol) {
    var positions = [];
    for (var r = 0; r < rows; r++) {
        for (var c = 0; c < cols; c++) {
            // Exclude 3x3 area around safe cell
            if (Math.abs(r - safeRow) <= 1 && Math.abs(c - safeCol) <= 1) {
                continue;
            }
            positions.push({ row: r, col: c });
        }
    }

    shuffle(positions);

    var minesToPlace = Math.min(totalMines, positions.length);
    for (var i = 0; i < minesToPlace; i++) {
        board[positions[i].row][positions[i].col].mine = true;
    }
}

先收集所有「可以放雷」的位置（排除安全区），然后 shuffle 打乱，取前 N 个放雷。

这里有个边界情况我一开始没想到：Math.min(totalMines, positions.length) 这行。如果棋盘太小、雷太多，排除了 3x3 安全区之后可放的位置不够怎么办？比如 5x5 的棋盘放 20 颗雷，排除 9 个安全格后只剩 16 个位置。没有这个 Math.min 的话，数组越界直接报错。虽然正常游戏不太会出现这种情况，但自定义难度的时候用户什么参数都可能填。

还有个细节：排除的是 3x3 区域而不是单个格子。为什么？因为如果只排除点击的那一个格子，第一次点击虽然不会死，但可能翻开一个数字 8（周围全是雷），体验很差。排除 3x3 保证第一次点击至少能展开一小片区域，给玩家一个好的开局。

像素级还原的 CSS 挑战

Windows XP 扫雷那个经典的 3D 外观，全靠 CSS 实现：

.cell-raised {
  border-top: 2px solid #fff;
  border-left: 2px solid #fff;
  border-bottom: 2px solid #808080;
  border-right: 2px solid #808080;
}

.cell-sunken {
  border-top: 1px solid #808080;
  border-left: 1px solid #808080;
  border-bottom: 1px solid #fff;
  border-right: 1px solid #fff;
}

上边和左边用亮色，下边和右边用暗色，就能模拟出光照从左上方打过来的 3D 效果。翻开的格子反过来，就是凹陷的效果。注意凸起是 2px 边框，凹陷是 1px，这个细节也是对着原版截图一点点调出来的。

LED 数字显示器也是纯 CSS 画的，用七段数码管的方式拼出 0-9。计时器和雷数计数器都用这个组件。

说起来简单，但调到「看起来对」花了不少时间。我对着 Windows XP 虚拟机的截图一个像素一个像素地比对，调颜色、调边框宽度、调间距。强迫症发作的时候真的停不下来。

PWA 离线支持

扫雷这种游戏太适合做 PWA 了。断网环境下也能玩，安装到手机桌面之后和原生 App 体验一模一样。

Service Worker 缓存了所有静态资源，第一次加载之后就完全不需要网络了。加上整个游戏零外部依赖，离线体验和在线完全一致。

技术对比

两个项目放在一起看，差异还挺大的：

星域战机是「大而全」，什么都自己造轮子；扫雷是「小而精」，在有限的规模里把每个细节打磨到位。两种开发体验都很有意思。

共同的设计哲学

虽然两个项目规模差很多，但有几个原则是一致的：

零依赖。 没有 React，没有 Vue，没有 jQuery，没有任何 npm 包。所有代码都是从零写的。这不是为了装逼，是为了学习。用框架的时候，很多底层细节被封装掉了，你不知道 Canvas 怎么画一个圆，不知道事件委托怎么实现，不知道音频合成的原理。自己写一遍，这些东西就真的变成你的了。

数据驱动。 星域战机的技能配置是数据驱动，扫雷的主题和成就也是数据驱动。把「是什么」和「怎么做」分开，代码会清晰很多。加内容不需要改逻辑，改逻辑不会破坏内容。

程序化音效。 两个游戏都没有音频文件，全部用 Web Audio API 实时合成。省带宽，省加载时间，而且可以动态调整参数（比如根据连击数改变音调）。

渐进增强。 核心功能不依赖任何高级 API。Web Audio 不支持？静音也能玩。Service Worker 不支持？在线也能玩。触屏设备？也做了适配。不会因为某个 API 不可用就整个游戏崩掉。

写在最后

这两个游戏是在备考间隙做的。晚上回来，刷完当天的任务，如果还有精力，就写一会儿代码。有时候是半小时，有时候是两小时。星域战机断断续续写了两周，扫雷集中三天搞定。

对我来说，写代码是一种很好的减压方式。和刷题不同，写代码的时候你在创造东西，看着一个游戏从空白画布变成能玩的成品，那种成就感是做对一道数学题给不了的。

回头看这一年多的项目：博客让我入了前端的门，TimeMark 让我理解了全栈和 Docker，这两个游戏让我真正掌握了 Vanilla JS 的底层能力。每个项目都在前一个的基础上往前走了一步。

高考之后，我想试试用真正的游戏引擎做点东西。Godot 或者 Unity，做一个有完整剧情的小游戏。也可能会继续用 Web 技术，毕竟浏览器的能力还远没被我榨干。

不管怎样，这两个项目算是高中阶段的一个句号。

好了，该去背英语了。

试玩链接：

• 星域战机：game1.the37777777.top/ulw
• 经典扫雷：game2.the37777777.top

去年过年的时候，我忘了给一个长辈发生日祝福。不是不想发，是真的忘了。我妈提醒我的时候已经过了两天，场面一度很尴尬。

后来我想，能不能做个工具自动提醒我？上网搜了一圈，发现要么是手机日历（不支持农历），要么是付费 App（一年几十块），要么是那种企业级的日程管理系统（杀鸡用牛刀）。我家里有台 NAS，跑着飞牛OS，上面已经有好几个 Docker 容器了。如果能做一个 Docker 应用，一键部署到 NAS 上，岂不是完美？

就这样，TimeMark 诞生了。这是我做完博客之后的第二个项目，也是我第一次接触 Docker 开发。

TimeMark 是什么

简单说，TimeMark 是一个智能事件提醒系统。你把家人朋友的生日、纪念日录进去，它会在指定时间通过微信、QQ、钉钉、飞书、邮件、Bark 等渠道自动发通知给你。

听起来不复杂对吧？但有几个点让它变得有意思：

• 农历支持。我奶奶的生日是农历的，每年对应的公历日期都不一样，还要处理闰月的情况。
• NAS 友好。专门为家用 NAS 设计，J4125、N5105 这种低功耗处理器也能跑。
• 一键部署。三行命令搞定，不需要懂代码。

目前支持飞牛OS、群晖、威联通、铁威马这几个主流 NAS 系统。

技术选型：为什么选这些

做博客的时候我用了 Next.js + Tailwind CSS，算是入了前端的门。TimeMark 是全栈项目，前后端都要写，所以技术选型花了不少心思。

后端框架选了 Hono。 那段时间刷 GitHub Trending，发现 Hono 经常上榜。点进去一看：轻量、快、TypeScript 原生支持、API 设计很优雅。试了一下，确实比 Express 写起来舒服。而且 Hono 的中间件机制很灵活，做鉴权、日志这些很方便。

数据库选了 sql.js（SQLite）。 这个选择其实是踩了坑之后才做的，后面会讲。最终选 sql.js 的原因很简单：零依赖，数据就是一个文件，NAS 用户备份的时候直接拷贝就行。做博客的时候我就学到了一个道理：能简单就别复杂。

前端还是 React + TailwindCSS。 熟悉嘛，博客项目打下的基础直接用上了。

项目结构用了 pnpm workspace monorepo。 前端和后端放在一个仓库里，共享 TypeScript 类型定义。比如一个 Event 类型，前端后端用的是同一份定义，改一处两边都生效。类型安全这东西，用过就回不去了。

架构设计参考了不少开源项目，Docker 最佳实践也翻了官方文档好几遍。

架构演进：从过度设计到大道至简

v1.x 时代：三个容器的「豪华配置」

第一版的 TimeMark，我用了 PostgreSQL 做数据库，Redis + Bull 做任务队列，加上应用本身，一共三个 Docker 容器。

为什么这么设计？因为我看的教程和开源项目都是这么搞的。PostgreSQL 是「正经」数据库，Redis 做缓存和消息队列是「业界标准」，Bull 是 Node.js 生态里最流行的任务调度库。一切看起来都很「专业」。

然后 NAS 用户开始反馈了。

"这玩意吃了我 800MB 内存，我 NAS 一共才 4GB。" "J4125 跑你这个 CPU 占用 30%，我还跑着其他服务呢。" "就一个提醒工具，为什么要装 PostgreSQL？"

说实话，他们说得对。一个生日提醒系统，数据量撑死几百条，用 PostgreSQL 确实是大炮打蚊子。Redis 就更离谱了，我用它只是为了跑定时任务，完全可以用更轻量的方案替代。

v2.0 重写：砍掉一切不必要的

想明白之后，我花了两周重写了整个后端：

• PostgreSQL → sql.js。SQLite 跑在 WASM 里，不需要单独的数据库容器。数据就是一个 .db 文件。
• Redis + Bull → Croner。Croner 是一个纯 JavaScript 的 cron 调度器，几十 KB 大小，功能完全够用。
• 三容器 → 单容器。只需要一个 Docker 容器，内存占用从 800MB 降到 256MB，减少了 70%。

这次重写让我真正理解了一句话：不要为了用技术而用技术。 选型的时候应该先想清楚需求是什么，而不是什么流行就用什么。一个面向家庭用户的小工具，简单可靠比「架构优雅」重要一万倍。

踩过的坑

做这个项目踩的坑比做博客多得多。挑几个印象最深的说说。

Docker Hub 用户名：连改了 6 次

第一次往 Docker Hub 发布镜像，我以为随便填个用户名就行。结果 push 的时候一直报错，说找不到仓库。

折腾了半天才搞明白：Docker Hub 的镜像名格式是 用户名/镜像名，这个用户名必须和你的 Docker Hub 账号完全一致。我一开始注册的时候手滑打错了，后来又改了好几次。翻 git log 能看到连续 6 个 commit 都在改这个用户名：wfffff666、xxxxxf666、xfffff666……

现在回头看那段 git 历史，挺好笑的。但当时真的很崩溃，因为 CI/CD 流水线一直跑不通，每次改完都要等 GitHub Actions 重新构建。

最终确定的镜像地址是 xfffff666/timemark:latest。

SQL 方言不兼容：PostgreSQL 到 SQLite 的迁移噩梦

v2.0 把数据库从 PostgreSQL 换成 sql.js 的时候，我天真地以为改个连接字符串就行了。

大错特错。

PostgreSQL 和 SQLite 的 SQL 方言差异比我想象的大得多。TO_CHAR() 函数在 SQLite 里根本不存在，日期格式化要用 strftime()。PostgreSQL 的布尔值是 true/false，SQLite 里是 1/0。Date 对象的处理方式也完全不同。

我不得不把所有涉及日期的查询全部重写。光这一项就改了好几天，提交了十几个 commit。有些 bug 还很隐蔽，比如农历转换后的日期比较逻辑，在 PostgreSQL 里跑得好好的，换到 SQLite 就出错了，因为两边的日期排序规则不一样。

教训：换数据库不是换个驱动那么简单。SQL 看起来是「标准」的，但每个数据库都有自己的方言和怪癖。

crypto.randomUUID 在 NAS 上不工作

这个 bug 让我排查了很久。本地开发一切正常，部署到 NAS 上之后，用户注册和登录功能直接崩了。

报错信息是 crypto.randomUUID is not a function。

查了一圈才知道：crypto.randomUUID() 需要「安全上下文」（Secure Context），也就是 HTTPS 环境。但 NAS 用户大多是通过局域网 HTTP 访问的，没有 HTTPS。

解决方案是加了一个 fallback：

function generateUUID(): string {
  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
    return crypto.randomUUID()
  }
  // fallback: 手动拼接 UUID v4
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
    const r = (Math.random() * 16) | 0
    const v = c === 'x' ? r : (r & 0x3) | 0x8
    return v.toString(16)
  })
}

这种「本地没问题，线上就炸」的 bug 是最烦人的。以后写代码得多想想目标用户的实际使用环境。

时区问题：经典的差 8 小时

做 Web 开发的人大概都会遇到时区问题，我也没逃过。

用户反馈说登录时间显示不对，明明是下午三点登录的，系统显示的是早上七点。差了刚好 8 小时。

原因很简单：服务端存的是 UTC 时间，前端展示的时候没有做时区转换。中国是 UTC+8，所以差了 8 小时。

听起来很好修对吧？但实际上我前前后后改了好几次才彻底修好。因为时区问题不只出现在登录时间，事件提醒的触发时间、农历日期的计算、cron 表达式的解析……到处都有时区的影子。每修一个地方就发现另一个地方也有问题。

最后我统一了策略：服务端全部用 UTC 存储和计算，只在返回给前端的时候转换成 Asia/Shanghai。

Docker 容器里的 DNS 解析失败

有用户反馈说通知发不出去，看日志发现是 DNS 解析失败。容器里 ping 任何域名都不通。

这是国内网络环境的老问题了。Docker 默认用的 DNS 是 8.8.8.8（Google DNS），在国内很多网络环境下不稳定。

解决方案是在 docker-compose.yml 里加上国内 DNS：

dns:
  - 223.5.5.5 # 阿里 DNS
  - 8.8.8.8 # Google DNS（备用）

223.5.5.5 是阿里云的公共 DNS，国内解析速度快、稳定性好。加上之后问题就解决了。

几个有意思的功能

TimeMark 的功能不少，挑几个我觉得有意思的说说。

农历支持是最费心思的。我用了 lunar-javascript 这个库来做农历和公历的互转。农历有闰月，比如闰四月，这种情况下同一个农历生日在公历上的日期会跳来跳去。我写了一套逻辑来处理这些边界情况，测试用例写了一大堆。

通知渠道目前支持 35 个以上，覆盖了微信（Server 酱、PushPlus）、QQ、Telegram、钉钉、飞书、邮件、Bark、Gotify 等等。这些渠道的 API 各不相同，我抽象了一个统一的通知接口，新增渠道只需要实现一个 adapter 就行。

安全方面也下了功夫。JWT 做身份认证，bcrypt 做密码哈希，AES-256 加密存储第三方通知渠道的密钥（比如邮箱密码、API Token），还有登录失败锁定机制防暴力破解。虽然是个小工具，但跑在 NAS 上，安全不能马虎。

还有个小功能我挺喜欢的：智能关系映射。你输入「我爸」，系统会自动识别成「父亲」这个关系类型，方便后续分类和展示。

部署方式

说了这么多，怎么用呢？

最快的方式：三行命令

mkdir timemark && cd timemark
curl -sSL https://raw.githubusercontent.com/WXFffff666/timemark-docker/master/docker-compose.dockerhub.yml -o docker-compose.yml
docker compose up -d

完整的 docker-compose.yml

如果你想手动创建配置文件，内容就这么多：

# TimeMark 一键部署 (Docker Hub)
# 使用: docker compose up -d

services:
  app:
    image: xfffff666/timemark:latest
    container_name: timemark-app
    restart: unless-stopped
    ports:
      - '3000:3000'
    environment:
      TZ: Asia/Shanghai
    dns:
      - 223.5.5.5
      - 8.8.8.8
    volumes:
      - ./data:/app/data

就这 18 行，没了。不需要配置数据库，不需要配置 Redis，不需要设置环境变量。docker compose up -d 之后访问 http://你的NAS的IP:3000 就能用了。

几个部署细节

端口冲突？ 如果 3000 端口被占了，改成别的就行：

ports:
  - '8080:3000' # 改成 8080 或者任何空闲端口

数据在哪？ 所有数据存在 ./data/timemark.db 这个 SQLite 文件里。备份的时候直接拷贝这个文件就行：

cp ./data/timemark.db ./data/timemark.db.bak

DNS 为什么要配？ 国内网络环境下，Docker 默认的 DNS（8.8.8.8）经常解析失败。加上 223.5.5.5（阿里 DNS）就稳了。这也是我踩坑踩出来的经验。

公网部署？ 如果要放到公网服务器上，建议自定义 JWT_SECRET 和 MASTER_KEY：

environment:
  TZ: Asia/Shanghai
  JWT_SECRET: 你自己生成一个随机字符串
  MASTER_KEY: 再生成一个随机字符串

镜像地址

飞牛OS、群晖、威联通、铁威马都能用。只要你的 NAS 支持 Docker，就没问题。

v2.1.0：继续打磨

v2.0 发布之后，我以为可以告一段落了。结果用了几天就发现还有很多可以改进的地方。

8 个新通知渠道

v2.0 的时候支持 27 个通知渠道，已经不少了。但我发现国内用户最常用的几个推送服务还没支持：Server 酱、PushPlus、Bark 这些。

于是我又加了 8 个新渠道：

加完之后渠道总数到了 38+。因为之前设计了统一的通知接口，新增渠道只需要实现一个 adapter，所以加起来还挺快的。每个渠道大概半天就能搞定，主要时间花在看各家的 API 文档上。

顺便还把邮件渠道做了分类重组，支持多账号选择了。比如你可以配置多个邮箱，创建事件的时候选择用哪个邮箱发通知。

零配置即开即用

v2.0 的时候，虽然已经是单容器了，但还是需要配置 JWT_SECRET 和 MASTER_KEY 这两个环境变量。有用户反馈说不知道怎么生成随机字符串，觉得麻烦。

想了想，确实没必要强制配置。对于家庭内网使用的场景，内置一个默认密钥就够了。于是我给所有环境变量都加了内置默认值：

• JWT_SECRET 和 MASTER_KEY 有内置默认值
• 默认管理员账号 admin / TimeMark@2026
• docker compose up -d 之后直接就能用，不需要改任何配置

当然，如果是公网部署，还是建议自定义密钥。但对于大多数 NAS 用户来说，零配置才是最友好的。

登录锁定升级

v2.0 的登录锁定是固定的：连续 5 次失败，锁定 15 分钟。但这样有个问题——攻击者等 15 分钟就能继续尝试。

v2.1.0 改成了线性叠加：第一次锁定 5 分钟，第二次 10 分钟，第三次 15 分钟……每次锁定时间递增。这样暴力破解的成本会越来越高。

CI 构建修复

加了 ClawBot（微信龙虾）渠道之后，CI 构建突然挂了。排查了一下，发现是两个问题：

1. ClawBot 依赖 nodemailer，但没有加到 package.json 里。本地开发的时候因为 node_modules 里有缓存所以没问题，CI 环境是干净安装就报错了。
2. ClawBot 的类型定义有问题，TypeScript 编译不过。

修了这两个问题之后 CI 就通了。这种「本地没问题，CI 就炸」的情况我在做博客的时候也遇到过，算是老朋友了。

这个项目教会我的

回头看，TimeMark 教会我的东西比博客项目多得多。

全栈开发的完整链路。 从前端 UI 到后端 API，从数据库设计到 Docker 打包，从 CI/CD 到镜像发布。每一环都自己来，虽然累，但对整个开发流程的理解深了很多。

Docker 多阶段构建。 为了减小镜像体积，我学了 multi-stage build。第一阶段用 Node.js 编译 TypeScript，第二阶段只拷贝编译产物和运行时依赖。最终镜像从 1GB+ 压缩到了几百 MB。

安全意识。 以前写代码不太在意安全，觉得「又没人攻击我」。但 TimeMark 要存用户的通知渠道密钥，这些东西泄露了是真的会出问题的。所以我认真学了加密、鉴权、防暴力破解这些知识。

架构重构的勇气。 v1.x 到 v2.0 的重写，等于把后端推翻重来。当时很纠结，毕竟 v1.x 已经能用了。但用户反馈摆在那里，不改不行。这次经历让我明白：代码不是写完就结束了，根据反馈持续改进才是常态。

CI/CD 自动化。 用 GitHub Actions 实现了自动构建和推送 Docker 镜像。每次 push 代码，Actions 会自动编译、打包、推送到 Docker Hub。再也不用手动 docker build 然后 docker push 了。

用户反馈的价值。 如果不是 NAS 用户告诉我「太重了」，我可能永远不会去做 v2.0 的重写。闭门造车做出来的东西，和真实用户需要的东西，往往差距很大。

写在最后

从博客到 TimeMark，每个项目都让我成长了一截。博客教会我前端开发和部署，TimeMark 教会我全栈开发和 Docker。

从 v1.x 到 v2.0 再到 v2.1.0，每次迭代都是在用户反馈的基础上打磨。这个项目不会「完成」，它会一直跟着需求进化。

下一个项目会是什么？还不确定。但我知道，只要一直做下去，一直学下去，总会越来越好的。

如果你也是学生，也想做点什么，别犹豫，直接开始。第一版肯定很烂，没关系。我的第一版也很烂，三个容器吃 800MB 内存那种烂。但做着做着，就会越来越好。

继续写代码，继续踩坑，继续成长。

大家好，我是 XFffff，一名高中生。这是我第一次尝试搭建自己的个人博客。说实话，一开始我对前端开发了解得不多，只是觉得有个自己的博客很酷，可以记录学习和生活。没想到这个过程比我想象的要复杂得多，但也更有趣。

这篇文章记录了我从零开始搭建博客的完整过程，包括遇到的各种问题和解决方法，特别是今天（2月15日）一整天的性能优化历程。希望能帮到和我一样想做博客的同学。

第一步：选择技术方案

一开始我很迷茫，不知道该用什么技术。在网上搜索了很久，看了很多教程，最后决定用这套方案：

为什么不用 Vercel？

虽然很多教程都推荐 Vercel，但我选择了 Cloudflare Pages，因为：

• 完全免费，没有流量限制
• 全球 CDN，访问速度快
• 和域名管理在一起，方便

第二步：找到合适的模板

作为第一次做项目，我不可能从零开始写所有代码。在 GitHub 上找了很久，最后发现了 mengke.me 这个开源项目。

这个项目功能很完善：

• ✅ 支持 Markdown 写文章
• ✅ 有深色模式
• ✅ 可以搜索文章
• ✅ 自动生成 RSS
• ✅ 手机和电脑都能正常显示

我把它 Fork 到自己的 GitHub，然后开始改造。

# 克隆项目到本地
git clone https://github.com/WXFffff666/my-blog.git
cd my-blog

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

打开 http://localhost:3434，看到页面成功显示，心里特别激动！

第三步：个性化定制

修改个人信息

第一件事就是把模板里的信息改成自己的。主要修改这几个文件：

1. 个人信息（data/author-info.ts）

export const AUTHOR_INFO = {
  name: 'XFffff',
  description: '一个热爱学习的高中生',
  email: 'my-email@example.com',
  identity: 'Student | Learning',
  address: {
    city: 'Guilin, China',
    flag: 'flag-china',
    timeZone: 8,
  },
  social: {
    github: 'https://github.com/WXFffff666',
  },
}

注意：不要填真实姓名、手机号、详细地址这些敏感信息！

2. 网站信息（data/site-metadata.ts）

export const SITE_METADATA = {
  title: 'XFffff 的个人博客',
  author: 'XFffff',
  siteUrl: 'https://blog.the37777777.top',
  locale: 'zh-CN',
  language: 'zh-CN',
}

写第一篇文章

在 data/blog/202602/ 目录下创建 Hello_World.mdx：

---
title: 'Hello World - 我的第一篇博客'
date: '2026-02-12'
tags: ['随笔']
draft: false
summary: '这是我的第一篇博客文章！'
---

## 你好，世界！

这是我的第一篇博客文章。从今天开始，我要记录自己的学习和成长。

希望能坚持下去！

保存后刷新页面，文章就出现了！那一刻真的很有成就感。

第四步：部署到 Cloudflare Pages

本地运行成功后，就要部署到网上了。这一步遇到了不少问题。

配置静态导出

Cloudflare Pages 需要静态文件，所以要修改 next.config.js：

const nextConfig = {
  output: 'export', // 静态导出
  images: {
    unoptimized: true, // 必须禁用图片优化
  },
}

遇到的第一个错误

运行 pnpm build 时报错：

Page "/snippets/[...slug]" is missing "generateStaticParams()"

原因：项目里有个 snippets 目录，但我还没有添加任何内容。

解决：直接删除 app/snippets/ 目录，等以后有内容了再加回来。

创建 Cloudflare Pages 项目

1. 登录 Cloudflare Dashboard
2. 左侧菜单 → Workers 和 Pages
3. 点击 创建 → 选择 Pages 标签页
4. 连接 GitHub 仓库

重要配置：

绑定自定义域名

Cloudflare 会给一个 xxx.pages.dev 的临时域名，但我想用自己的域名。

1. 进入 Pages 项目 → 自定义域
2. 添加域名 blog.the37777777.top
3. Cloudflare 自动添加 DNS 记录
4. 等待 5-10 分钟生效

访问自己的域名，博客成功上线了！那一刻真的超级激动！

第五步：深色模式渲染优化（今天的重头戏）

博客上线后，我发现深色模式有严重的渲染问题：快速滚动时，文字会闪烁消失，非常卡顿。这个问题困扰了我一整天，但最终找到了解决方案。

问题现象

• 在深色模式下快速滚动页面
• 部分文字会闪烁、消失
• 有些文字清晰，有些文字模糊
• Footer 的文字清晰，但首页的文字模糊

排查过程

尝试 1：移除 PageTransition 的 transform

我发现 PageTransition 组件使用了 translate-y-2，这会创建 GPU 渲染层。

// 修改前
<div className="translate-y-2 opacity-0">

// 修改后
<div className="opacity-0">

结果：❌ 还是会闪烁

尝试 2：移除所有动画的 transform

检查了所有动画，发现很多地方使用了 transform：

/* CSS 中的动画 */
@keyframes fade-in-up {
  from {
    opacity: 0;
    transform: translateY(20px); /* ← 问题所在 */
  }
}

全部改成只用 opacity：

@keyframes fade-in-up {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

结果：❌ 还是有问题

尝试 3：移除 Greeting 的 bg-clip-text

发现 Greeting 组件使用了 bg-clip-text 和渐变动画：

// 修改前
<div className="bg-clip-text text-transparent animate-text-shimmer">

// 修改后
<div className="text-violet-600">

结果：❌ 还是不行

尝试 4：对比原作者项目（找到根本原因！）

我仔细对比了原作者的项目，发现了关键差异：

我的配置：

// layout.tsx
<body className="dark:bg-black">  // 纯黑 #000000

// background.tsx
<div className="dark:bg-[#000000]">  // 纯黑

// tailwind.config.js
dark: {
  bg: '#050505',  // 极致深黑
}

原作者的配置：

// layout.tsx
<body className="dark:bg-dark">  // 深灰色

// tailwind.config.js
dark: '#1f1f1f',  // 深灰色，不是纯黑！

发现问题：纯黑背景（#000000 或 #050505）在某些浏览器和操作系统上会导致字体渲染问题！

最终解决方案

将所有深色背景从纯黑改为深灰色 #1f1f1f：

// layout.tsx
<body className="dark:bg-dark-bg">

// background.tsx
<div className="dark:bg-[#1f1f1f]">

// tailwind.config.js
dark: {
  bg: '#1f1f1f',  // 深灰色
}

结果：✅ 完美解决！深色模式滚动完全流畅，不再闪烁！

为什么深灰色不会糊？

• #1f1f1f 虽然看起来也很黑，但它不是纯黑
• 这个颜色值在浏览器渲染引擎中不会触发某些特殊的优化路径
• 原作者也是用这个颜色，证明它是稳定可靠的

教训：有时候问题的根源不在代码逻辑，而在一些看似无关紧要的细节（比如背景颜色）。

第六步：图片加载优化

解决了深色模式问题后，我发现快速滚动时，下面会出现白条（内容还没渲染出来）。这是图片加载慢导致的。

优化方案

1. 预加载首屏图片

// latest-posts.tsx
{
  posts.map((post, index) => <BlogCard key={post.slug} post={post} priority={index < 3} />)
}

前 3 篇文章的图片使用 priority={true}，浏览器会优先加载。

2. 添加渐变占位符

// blog-card.tsx
<div className="relative h-48 w-full overflow-hidden bg-gradient-to-br from-gray-100 to-gray-200 dark:from-[#121212] dark:to-[#1a1a1a]">
  <Image src={coverImage} alt={title} priority={priority} />
</div>

图片加载前显示渐变背景，视觉上更平滑。

3. 优化图片淡入效果

// image.tsx
<NextImage
  className={clsx('transition-opacity duration-300', loaded ? 'opacity-100' : 'opacity-0')}
  onLoad={onLoad}
/>

图片加载完成后淡入显示，更自然。

结果：✅ 快速滚动时不再出现明显的白条！

第七步：导航栏交互优化

博客基本完善后，我开始优化细节。发现导航栏 hover 时有个放大动画，但放大过程中会模糊。

问题分析

导航栏使用了 hover:scale-[1.005]，scale 变换会导致字体模糊。

尝试的方案

方案 1：移除 scale，改用阴影 + 上移

<nav className="hover:shadow-xl hover:-translate-y-0.5">

结果：✅ 完全不会模糊，但上移有点突兀

方案 2：保留 scale，添加 GPU 优化（最终方案）

<nav
  className="hover:scale-[1.005]"
  style={{
    willChange: 'transform',
    transform: 'translateZ(0)',
    backfaceVisibility: 'hidden',
    WebkitFontSmoothing: 'subpixel-antialiased',
  }}
>

GPU 优化原理：

• willChange: 'transform' - 提示浏览器会有变换
• transform: translateZ(0) - 强制创建 GPU 渲染层
• backfaceVisibility: 'hidden' - 隐藏背面，提升性能
• WebkitFontSmoothing: 'subpixel-antialiased' - 亚像素级抗锯齿

结果：✅ 保留了放大效果，模糊感大幅减少！

经验总结

1. 技术选型很重要

• Next.js 静态导出性能很好，适合博客
• Cloudflare Pages 免费额度够用，速度也快
• 找一个好的开源模板可以节省很多时间

2. 遇到问题不要慌

• 先对比原作者的代码，找出差异
• 逐步修复，每次只改一个地方
• 分别测试电脑端和移动端
• 善用浏览器开发者工具

3. 性能优化要系统思考

• 深色模式问题可能是背景颜色导致的
• 图片加载要预加载首屏内容
• GPU 优化可以减少 transform 的模糊感
• 不要过度使用动画和特效

4. 细节决定体验

• 背景颜色不要用纯黑，用深灰色
• 图片要有占位符，避免白屏
• 动画要流畅，不能卡顿
• 移动端和电脑端要分别优化

5. 学会阅读源码

• 遇到问题时，对比原作者的代码
• 理解每一行代码的作用
• 不要盲目复制粘贴
• 学会举一反三

后续开发：从初版到液态玻璃

博客上线之后，我以为可以歇一歇了。结果完全停不下来——每天都能想到新功能要加，新 bug 要修。从 2 月到 4 月，这个博客经历了一次又一次的迭代，最终变成了现在的样子。

功能大爆发

上线后的两个月里，我一口气加了 11 个新功能。说实话，有些功能是我自己想要的，有些是看到别人的博客觉得「这个好酷，我也要」。

阅读进度条 + TOC 增强。 文章顶部加了一个进度条，滚动的时候能看到读了多少。目录（TOC）也做了增强，在手机上变成了一个抽屉式的侧边栏，不会挡住正文。

相关文章推荐 + 系列导航。 每篇文章底部会推荐相关的文章，算法是根据标签重合度打分的。还加了「文章系列」功能，比如这篇和 TimeMark 那篇就属于「我的开发之旅」系列，可以按顺序浏览。

Sandpack 可运行代码块。 这个是我最喜欢的功能之一。文章里的 JavaScript/TypeScript/HTML/CSS 代码块可以直接运行！用的是 CodeSandbox 的 Sandpack 组件，懒加载的，不影响页面性能。

OG 图片自动生成。 分享文章到社交媒体的时候，会自动生成一张好看的封面图。这个是构建时生成的，不需要运行时渲染。

Service Worker + 离线支持。 加了 Service Worker 做缓存，断网了也能看之前访问过的页面。顺便还做了一个友链申请表单。

键盘快捷键 + Changelog + Snippets 筛选。 按 ? 可以查看所有快捷键，加了一个 Changelog 页面记录版本更新，Snippets 页面支持按标签筛选了。

这些功能加起来，提交了十几个 commit。每次加完一个功能都要跑一遍 pnpm build，确保静态导出没问题。Cloudflare Pages 是纯静态部署，任何需要服务端的功能都不能用，这个限制反而让我学会了很多静态站点的技巧。

代码规范化重构

功能加多了之后，项目结构开始变得混乱。CSS 文件散落在各处，图片目录没有统一规范，有些文件放错了位置。

我花了两天时间做了一次大重构：

• 把 css/ 目录统一改名为 styles/
• 图片目录按用途分类：covers/（封面）、banners/（横幅）、posts/（文章配图）
• 移除了没用的测试文件和示例文件
• 把文档统一放到 docs/ 目录

重构的过程很枯燥，但做完之后整个项目清爽了很多。以后找文件也方便了。

中文标签 404 修复

这个 bug 困扰了我好一阵子。博客的标签系统支持中文标签（比如「技术」「前端」），在本地开发的时候一切正常，但部署到 Cloudflare Pages 之后，点击中文标签就 404。

排查了半天，发现是 encodeURI 的问题。之前代码里对标签做了 URL 编码，但 Cloudflare Pages 的静态文件路径不需要编码。移除了多余的 encodeURI 调用就好了。

顺便还做了一个标签显示名映射（tag-names.json），这样标签页上能显示原始的中文名称，而不是 URL 编码后的乱码。

液态玻璃 UI 改造

这是最大的一次改动。

起因是我看到了 Apple 的液态玻璃（Liquid Glass）设计风格，觉得特别好看。之前博客用的是「黑曜石玻璃」风格——深空灰背景加噪点纹理，虽然也不错，但看久了觉得有点沉闷。

我决定把整个博客改成液态玻璃风格。

一开始我想用 liquid-glass-react 这个 npm 包，但研究了一下发现它已经 10 个月没更新了，性能也不太好，还没有可访问性支持。最后决定自己用纯 CSS 实现。

液态玻璃的核心就是 backdrop-filter: blur() 加上半透明背景。我设计了 4 个层级：

/* standard - 普通组件 */
background: rgba(255, 255, 255, 0.15);
backdrop-filter: blur(20px) saturate(1.8);

/* elevated - 突出组件（导航栏、卡片） */
background: rgba(255, 255, 255, 0.2);
backdrop-filter: blur(24px) saturate(2);

/* subtle - 低调组件（标签、徽章） */
background: rgba(255, 255, 255, 0.08);
backdrop-filter: blur(12px);

/* input - 输入框 */
background: rgba(255, 255, 255, 0.12);
backdrop-filter: blur(16px);

背景色从深空灰改成了天蓝色 #bfdbfe（浅色模式）和 #1f1f1f（深色模式）。

改造过程中踩了不少坑。一开始用了 SVG 滤镜做扭曲效果，结果在某些浏览器上会出现奇怪的变形和闪烁。后来去掉了 SVG 扭曲，只保留了 CSS 的 blur 和 saturate，效果反而更好。

还有一个问题是白色边框。液态玻璃组件之前有白色边框和阴影，在天蓝色背景上看起来很突兀。我把所有组件的白色边框和阴影都去掉了，改用更微妙的透明度变化来区分层次。

最后还要把 6 个代码块相关的 MDX 组件也适配液态玻璃风格，确保代码块在新设计系统下看起来协调。

整个改造涉及了 26 个组件，提交了好几个 commit。虽然工作量很大，但最终效果我很满意。

滑动 Pill 导航指示器

液态玻璃改造完之后，我觉得导航栏还可以更酷一点。

于是加了一个滑动的玻璃药丸（Pill）指示器。当你切换导航项的时候，一个半透明的玻璃药丸会平滑地滑动到当前选中的位置。动画用了 spring easing（弹簧缓动），有一种很自然的弹性感。

这个效果实现起来不难，但调参数花了不少时间。弹簧的刚度、阻尼、质量都会影响动画的感觉，太硬了像机械，太软了像果冻。最后调到一个我觉得刚好的状态。

kbar 搜索位移修复

这个 bug 是最后修的，也是最烦人的。

博客用了 kbar 做搜索（按 Ctrl+K 打开）。kbar 打开的时候会给 body 加 overflow: hidden，防止背景滚动。但这样做有个副作用：滚动条消失了，页面内容会往右移动一点点（大概 15-17 像素），看起来就像页面「抖」了一下。

我前前后后试了好几种方案：

1. 用 padding-right 补偿滚动条宽度 —— 不行，因为 sticky header 的居中计算会受影响
2. 动态测量滚动条宽度再补偿 —— 太复杂，而且不同浏览器滚动条宽度不一样
3. 最终方案：直接用 CSS 覆盖 kbar 的行为

body[style*='overflow: hidden'] {
  overflow-y: scroll !important;
}

简单粗暴但有效。让 body 始终保持 overflow-y: scroll，滚动条一直在，就不会有位移了。kbar 的遮罩层本身就会阻止用户滚动，所以不影响功能。

有时候最简单的方案就是最好的方案。

写在最后

从开始搭建到现在，已经过去好几天了。特别是今天（2月15日），我花了一整天时间优化深色模式的渲染问题。这个过程中遇到了很多挫折，有时候真的很想放弃。但每次解决一个问题，那种成就感是无法形容的。

作为一个高中生，这是我第一次完整地做一个项目。虽然代码写得不够好，但我学到了很多：

• 学会了如何阅读文档和源码
• 学会了如何调试和定位问题
• 学会了如何系统地优化性能
• 学会了如何坚持下去

最重要的是，我有了一个属于自己的博客，可以记录学习和成长。

如果你也想做一个博客，不要害怕，大胆去试！遇到问题很正常，解决问题的过程就是成长的过程。

后来我把浏览量统计功能去掉了，博客现在是一个纯静态站点，部署在 Cloudflare Pages 上，简单又稳定。

希望这篇文章能帮到和我一样的初学者。如果你有问题，欢迎交流！

相关资源

• 我的博客：https://blog.the37777777.top
• 原项目地址：https://github.com/mk965/mengke.me
• Next.js 官方文档：https://nextjs.org/docs
• Cloudflare Pages 文档：https://developers.cloudflare.com/pages/

下一步计划

• ✅ 添加了 Giscus 评论系统
• ✅ 做了 TimeMark 生日提醒系统（我的第一个 Docker 项目！）
• ✅ 添加了 11 个新功能（进度条、系列导航、Sandpack、OG 图片等）
• ✅ 完成了液态玻璃 UI 改造
• ✅ 修复了中文标签 404 问题
• ✅ 代码规范化重构
• ✅ 完成 v2.0 全站增强（50+ 项改进，15 个 MDX 组件，Pagefind 搜索）
• 📝 持续写文章，记录学习
• 🎨 继续打磨液态玻璃细节
• 🚀 探索更多有趣的项目

加油！💪