上周五晚上九点半左右，我坐在电脑前正准备把一个功能分支合并进主分支。

在网页上点下 Merge 后，浏览器顶部那条蓝色的进度条卡在中间不动了。过了几秒，整页直接跳出一片空白，随后返回了 500 错误。我顺手强制刷新页面，依然无法加载。

第一反应是以为本地网络代理出了问题，我随手新开了一个标签页刷了下某个屎黄色站点，视频秒开，网络非常顺畅。再切回 VS Code，右下角 Copilot 图标也悄悄亮起了无法连接的提示。

这时候在技术交流群里已经有人开始发截图问：“GitHub 是不是挂了？”。然而群里的反馈并不一致：有的朋友说完全打不开，有的朋友却说自己拉取代码一切正常。推特时间线上也有不少开发者陆续晒出 500 报错页面。

大家一边在群里发表情包，一边排查到底发生了什么。这种“部分地区能用、部分地区报错”的半瘫痪状态持续了很久。部分用户的 PR 无法合并、CI/CD 停滞，VS Code 里的 Copilot 也频频断连。

一直到第二天早上，经历了整整 7 个多小时的局部震荡后，GitHub Status 正式发布了事故复盘。报告里记录了这次事故的前因后果。

撇开那些过于晦涩的技术术语，我们用清晰、直白的方式，看看这场局部受损却波及极广的事故到底是怎么发生的。

来源：GitHub Status 事故报告

事故影响：部分服务与区域受阻

根据 GitHub Status 官方记录（ 8 月 17 日 13:28–21:15），本次事故持续了整整 7 小时 47 分钟。

需要先明确一个关键事实：本次事故并非全球全站彻底下线，主要受灾区域集中在 Central US 数据中心，表现为部分地区与部分服务的间歇性高错误率。

官方披露的核心受损指标相当直观：

• 网页端与 REST/GraphQL API 整体错误率峰值接近 20%（其余大部分正常流量依然可达）。
• 仓库 archive 与 raw content 的下载错误率攀升至约 50%。
• Issues、Pull Requests、Actions 和 Webhooks 出现大面积降级，Git 操作、Pages 与 Copilot 均受到不同程度冲击。
• 涉及企业级身份认证的 SAML/OIDC、SCIM 以及 Team Sync 路径同样出现局部故障。
• 采用 Data Residency 架构的企业客户，由于部分 Actions 工作流依赖 GitHub.com 托管的公开 Step 定义，也遭到级联波及。
• 与此同时，通过 GitHub CLI 和 GitHub App 使用 Copilot 的用户全程未受影响，受灾最严重的是 VS Code 等桌面客户端。

这种“有人正常、有人全挂”的局部异常，反而让排查变得更加扑朔迷离。

故障根因：容量配置盲区引发连锁阻塞

梳理官方报告可以发现，整场事故的源头来自一个容易被忽视的网络代理配置盲区：

1. Sidecar 代理触及并发上限：Central US 数据中心遭遇流量高峰，负责内部网络路由的单个 Istio sidecar pod 达到了并发连接上限。举个例子，就好比一个业务窗口虽然大门敞开，但门前的专用安检通道已经挤满了人，流量大到挤满通道，没法疏导。
2. 自动扩容指标未联动：自动扩缩容策略（HPA）当时只盯住了宿主业务服务的 CPU 和请求指标，未把 Sidecar 代理的并发负荷算进去。系统误以为容量充足，未及时启动弹性扩容。
3. 关键节点连接耗尽：局部的网络阻塞迅速扩散，直接导致上游 4 个关键 HAProxy 节点耗尽了连接与流量配额（flow limit）。
4. 认证通路大面积变慢：HAProxy 承载着网关身份鉴权的核心链路。一旦这里堵死，依赖鉴权验证的网页端、API、Actions 和 Copilot 服务立即陷入大面积延迟和超时。

认证网关如同整座系统的总闸机，闸机卡住后，内部即便各模块完好，外部用户也无法正常通行。

放大效应：客户端重试引发流量风暴

如果仅仅是局部网关卡顿，系统或许能较快排查并完成切换。真正让事故拉锯了近 8 个小时的关键，在于各层重试机制造成的流量放大。

平时遇到接口报错，大家最下意识的动作是什么？ 重试！不行就再点一次！接着连续狂按重试！ 大家总觉得“多试一次总能成”，而客户端程序更是在后台不知疲倦地把这个动作放大了成千上万倍。

在大规模故障场景下，未经节制的重试往往会演变成无意识的集群压迫：

• 鉴权与服务端响应延迟飙升。
• 客户端判定请求超时并自动触发重试。
• 网关层根据既定策略同样向下游追加重试。
• 呈几何级数叠加的重试流量，彻底挤占了负载均衡器与认证服务的全部可用带宽。

用户在 VS Code 里看到的只是一句“Copilot 登录超时”，而在服务端看来，这就如同几万名用户因为闸机稍慢了一拍，在几秒内疯狂连刷了几十次卡。

官方数据揭示了这一惊人事实：Copilot Token Service 日常请求量为 7–9K RPS，在重试叠加下被暴力推升至 70–100K RPS。整整 10 倍的畸形洪峰，直接让正在尝试恢复的服务再次过载。

此外，VS Code 内部存在一个潜伏的重试逻辑缺陷，当某个内部端点响应稍有延迟，编辑器便会进入快速循环补发，成为了阻碍恢复的核心堵点。

系统出现故障时，盲目的重试机制往往比原始缺陷更快拖垮整套架构。

跨区域调度与紧急止血手段

为了分流压力，GitHub 曾尝试将 Central US 的受阻流量切往 Northern Virginia 数据中心。

然而，跨区域调度只能改变请求的目的地，无法削减总调用量。数以百万计的客户端依然在以极高频率狂发重试，这股被放大了 10 倍的洪峰涌入新机房后，很快又给新的节点带来了沉重负担。

面对不断自我繁殖的恶性流量，GitHub 采取了数项强硬的阻断措施：

• 紧急推送配置，在网关层大幅降低自动重试的频次。
• 在负载均衡器层对部分 Copilot Token 请求直接返回 403 拒绝，强行截断客户端的重试死循环。
• 分站点、小批量逐步放行流量，给后端留出充足的缓冲时间。
• 同步暂停存在异常的 HAProxy 节点并完成状态恢复。

把盲目的重试流量完全压制住之后，整个服务集群才终于恢复平稳。

看完报告的几点体会

笔者作为每天都在使用 GitHub 的“麻瓜”开发者，读完这篇详实的官方复盘，还是发表一下感触吧：

• 强如行业标杆，也会被微小的配置盲区绊倒：业务服务与代理容器没有联动扩容、客户端埋着一个偶发的重试死循环，平时风平浪静，一旦遇上业务高峰就会引发连锁反应。
• 多机房调度并不是万能解药：面对失控的客户端重试风暴，单纯切机房只是把压力转移到另一个地方，甚至会迅速拖垮健康的备用节点。
• 详实透明的复盘具有极高价值：GitHub 没有用一句含糊的“系统维护”带过，而是把完整的故障周期（7 小时 47 分钟）、各业务受损指标（API 20%、下载 50%）、10 倍流量放大数据以及具体的改进举措完整公开。这种复盘不仅能给用户明确的交代，也是极具参考价值的工程教材，这里就不得不提一下国内某大厂，简直是反着来，恶心！

日常开发的避坑建议

GitHub 的架构规模非常庞大，但这场事故里暴露出的问题，也许在咱们的日常业务开发中同样很常见。结合这次教训，在和 Claude Fable ”老师“ 一起讨论过后，总结了几个小建议 😆：

1. 写重试时，务必加上退避与随机抖动

在封装前端请求、调用第三方 API 或消费消息队列时，不要简单写一个固定次数的死循环重试。

当下游服务真正崩溃时，成千上万个客户端同时无间隔重试，等于在联手攻击自己的后端。务必给重试加上最大尝试次数、递增的等待时间（指数退避）以及随机抖动（Jitter），错开并发请求，避免形成共振。

2. 监控业务指标，不只看进程存活状态

很多时候监控看板上的 CPU、内存一切平稳，容器状态也全绿，但核心业务可能已经不可用了。

这次事故中大部分基础服务进程并没有挂，瘫痪的是最前端的鉴权通道。日常开发中，应将接口真实状态码分布（4xx/5xx）、核心业务成功率与 耗时作为第一梯队的告警依据。

3. 关注调用链条上的每一层代理限制

在现代架构中，请求到达业务代码之前往往要经过浏览器、Nginx 反向代理、API 网关以及各种辅助服务。

业务代码写得再快，只要前面的 Nginx 连接数超标或辅助服务代理并发被打满，请求在进入代码前就已经失败了。做压力测试和容量规划时，必须将整条网络路径上的各层代理限制一并纳入评估。

最后

看来，强如 GitHub 这样的顶级工程师团队依然会犯错。在复杂系统中，很多看似为了“保障可用性”而编写的重试与容错逻辑，在极端场景下极易异化为击垮系统的最后一把推手。

建立重试边界，管控调用放大。下一次在代码中执行重试时，值得多为系统的极限承载力多考虑一些异常情况。

还有一个挺逗的事情，故障发生时，推特上有条关于 500 报错页的高赞调侃：

GitHub 不应该用独角兽作为服务不可用页面的 UI 图片，因为独角兽几乎看不到，而 GitHub 经常挂掉。

调侃归调侃，其实每次 GitHub 出故障，都是一次近距离学习大型服务故障防护的好机会 😆。

好了，今天就到这里，大家下次见~

我从 Codex 发布初期就开始使用了。当时由于预算有限，我既无力承担 20x 的高阶套餐，甚至连 5x 套餐也难以负担，只能勉强维持一个 Plus 订阅。

随着需求增长，单个 Plus 账号已无法满足我的使用量，于是我开始转向第三方中转服务。然而，随着 OpenAI 对低价账号打击力度的加大，中转服务的价格一路飙升。最终，我还是回归了官方渠道，并同时订阅了多个 Plus 账号以满足使用需求。

重度使用 Codex Plus 时，每周的额度往往很快耗尽。为了缓解这一问题，我曾尝试使用各类 CLI 工具及知名的 CC Switch 来辅助切换账号，并借此度过了一段过渡期。

然而，频繁地打开终端或通过 CC Switch 切换账号，再重启 Codex 的过程很快便令我感到厌倦。于是，我开始寻求一种更高效的解决方案。

我想要的其实是一个「账户池」

在寻找解决方案之前，我把我的需求捋了一遍：

• 几个账号一起认证登录，不要手动登出登入；
• 新会话自动挑余量最多的账号，实现负载均衡；
• 已在跑的会话不要动，长任务中途换账号效果不佳；
• 每个账号的用量状态能一眼看到，不需要逐个登录去查，满足一下个人查看额度的需求。

如上所述，我真正需要的是在“个人”与“官方服务”之间建立一层管理机制，而目前的官方客户端并不提供此项功能。

前几天刷 GitHub，正好刷到一个对上这个需求的项目：lidge-jun/opencodex。

这是一个本地驻留代理，所有 Codex 请求均经由它进行中转，并根据逻辑自动分发至指定的账号与模型。

账户池的两条关键规则

装好之后，再逐个添加账号。它有两个行为，正好对上我的需求。

现有会话将固定在原账户上。会话会绑定至启动它的账户，并在后续轮次中持续复用。即使在 SSH 或 tmux 等长会话场景下，也不会出现中途被切换账户的情况。

新会话将自动路由至负载最低的账户。系统会对比 5 小时、每周这三两时间窗口的用量，并选取压力最大的指标作为参考。当活跃账户达到阈值后，新会话将自动分配给余量充足的合格账户。

这两条规则相辅相成，有效解决了核心痛点：在高峰期，系统能够将压力均衡分配至多个账户；同时，对于正在进行的会话，又确保了其持久性，避免了中途切换带来的干扰。

仪表盘还能一键刷新所有账户配额，三个窗口的用量一屏看完，不用再逐个登录。

正好我手头还有 DeepSeek 和 SuperGrok，也一起添加进来！

在仪表盘中开启 Codex Auth 后，即可添加池账户，并可查看下一会话所分配的账户。若关闭自动切换功能，系统将始终锁定并使用当前账户。

另一个体现功底的细节是：当凭证失效时，系统会将账户标记为“需重新认证”，而非静默替换；当收到 429 配额限制响应时，账户会进入冷却状态，后续任务将自动切换至资源池中的其他可用账户。

该报错时即报错，因为代理后台擅自替换凭证反而会带来不可控的风险。

毫无存在感

其他工具很多是「有存在感」的：要你记得打开，或者记得反复切换。

而 Opencodex 其最大的优势在于：使用体验极其自然，几乎察觉不到它的存在。

模型选择器依然沿用 Codex 原生逻辑，命令调用与日常操作保持一致，会话及历史记录位置也未作变动。当某个账号达到使用上限时，系统会自动平滑切换至下一个可用池；若非仪表盘中留有请求日志，我甚至察觉不到系统已完成了接力。

我的直观感受是：将多个账号的配额整合在一起，体验如同拥有了一个无限额度的账号。这正是我所追求的理想状态——让工具隐于后台，使我能专注于任务本身。

想看后台在发生什么，打开 opencodex 的仪表盘：provider、账户配额、实时请求日志都非常完整，如果需要可以随时查看。

模型自助，随你喜欢

切换账号仅仅是我的入门需求；OpenCodeX 的核心优势在于它彻底开放了模型选择权。

它支持同时接入多家供应商，包括 Anthropic、Google、xAI、DeepSeek、GLM、Kimi、OpenRouter，以及本地的 Ollama。任何兼容 OpenAI 标准的端点均可接入，README 中列出的内置提供商已超过 40 家。配置完成后，所有模型将统一呈现在同一个选择器中。

我目前同时接入了 DeepSeek 和 OpenCode Go 套餐路由的一系列模型。使用时，只需在选择器中按需切换，体验与原生模型无异，甚至还能针对特定模型调节推理强度（reasoning effort）。

命令行里也可以用 -m 直接指定：

codex -m "anthropic/claude-opus-5" "解释这个 stack trace"

codex -m "ollama/llama3" "重构这个函数"

当省略 provider/ 前缀时，系统会自动路由至默认提供商，或根据模型名称模式进行匹配（例如，claude- 开头的模型将路由至 Anthropic，gpt- 开头的模型将路由至 OpenAI）。

Claude Code 也具备同样的功能。使用 ocx claude 启动时，其选择器逻辑与原生保持一致，用户可根据需求自由选择模型。

启用此服务后，您可以在各类 CLI 工具的模型切换列表中看到并使用您添加的所有模型，随心所欲。即使在 Claude Code 中使用 DeepSeek，体验也如同官方原生支持一般，完美契合您的使用习惯。

认证方式多种多样：xAI、Anthropic 及 Kimi 支持 OAuth 登录，可实现 Token 自动刷新；此外，也支持通过转发 Codex 登录、直接粘贴 API Key 或引用环境变量（${ENV_VAR}）进行配置。

它还是本机网关：其他软件也能接进来

在使用一段时间后，我发现了它的另一重身份：整台机器的本地网关。

OpenCodex 在本地 127.0.0.1:10100 提供统一的 API 入口。任何支持自定义请求地址的软件——无论是编辑器插件、自研脚本还是第三方客户端——均可将请求交由其处理，从而实现对同一供应商及账户池的复用。

这意味着本地工具无需再分别配置 API Key 或路由规则；只需在网关完成一次配置，即可实现全局共享。对于喜欢折腾工具的用户而言，这一设计极为实用。

以 AI 翻译软件为例，若需接入 OpenAI 服务，通常需要配置专属 API Key。此时，用户可以直接使用 OpenCodex 网关替代官方服务。鉴于目前许多软件已支持自定义 AI 服务商，这种应用方式具有非常广泛的适用性。

不是唯一方案，只是我个人喜欢

先说清楚，这类需求的方案不止一个。

再次介绍 CC Switch，一个开源跨平台桌面应用，统一管理 Claude Code、Codex、Gemini CLI 等工具的供应商配置，一键切换 provider，还带 MCP 和 Skills 管理。

OpenCodex 采取了截然不同的路径：通过常驻代理、账户自动接力，以及将模型直接集成至原生选择器，一旦配置完成，几乎可以实现无感使用。我个人更倾向于后者——我希望将模型切换的工作完全交给工具处理，从而彻底摆脱对此类琐事的关注。

类似思路的工具还有好几个，萝卜青菜各有所爱，选择自己喜欢的就好！

安装和几个实用命令

安装就两条命令，需要 Node 18+：

npm install -g @bitkyc08/opencodex
ocx start

ocx start 会启动代理，并打开 http://localhost:10100 的仪表盘；添加 provider、选模型、管账户都在网页里完成。随时可以跑 ocx gui 重新打开。想后台常驻、开机自启，用 ocx service。

几个常用命令：

• ocx status：看代理是否在运行
• ocx account list：查看账户和用量，脱敏显示
• ocx stop：停掉代理，并把 Codex 恢复成原始配置

最后一点尤为值得一提：在停止运行 OCX 后，Codex 的表现如同从未安装过 OpenCodex 一般——既无残留配置，也无僵尸进程。对于这类会修改客户端配置的工具而言，能够实现“干净退出”至关重要。

没有人希望软件卸载后仍留有冗余文件，正如没有人喜欢 macOS 在用户目录中留下 .DS_Store 文件一样 😆。

安装时如果遇到 bundled Bun runtime is missing，说明 npm 拦截了安装脚本。用 npm install -g --allow-scripts=bun @bitkyc08/opencodex 重装，别加 --ignore-scripts。

用之前要知道的几件事

若您打算尝试使用 OpenCodex，请先注意以下几点：

OpenCodex 是一个社区驱动的开源项目，与 OpenAI、Anthropic 等官方机构无任何关联。请注意，部分服务提供商（尤其是 Anthropic）可能会对通过第三方代理路由 API 流量的账户采取限制措施。正如 README 文档中所明确声明的：使用风险需由用户自行承担。

最后

回顾这一需求，初衷其实很简单：摆脱繁琐的账号切换，无需担忧配额耗尽，并能根据需求自由选择模型。

OpenCodex 将这三个痛点整合为一个常驻本地代理：通过自动轮询账号池和聚合多供应商接口，使其成为整台机器的统一网关。如果你也厌倦了在多个账号间频繁切换，花十分钟尝试一下非常值得。

AI 的发展实在太快，也许这个方案再过一段时间就过时，到时候如果有更好的方案，我还会分享出来给大家！

开发过程中，及时看到状态、找到资料，再配上一点有趣的交互，往往能省掉不少重复操作。这期继续分享几个可以直接留在工作流里的项目。

本期主要内容：

• CodexBar —— 在 macOS 菜单栏查看 AI 服务额度和重置时间
• Pane —— 在 Windows 托盘查看多个 AI 订阅的使用情况
• ai-agent-book —— 用开源书籍和配套代码学习 Agent
• grok-build —— 从源码拆解终端 AI Coding Agent
• TanStack Intent —— 让 Agent Skills 随 npm 包一起提供
• cnfast —— 更快的 Tailwind class 合并工具
• Sticker Forge —— 用 WebGL 制作可以撕开的互动贴纸
• Canvas UI —— 可复制到项目里的 Canvas 和 WebGL 组件库
• Takumi —— 将 JSX 和 HTML 渲染成图片、SVG 与动画
• Kinetics —— 基于弹簧物理的网页交互动效库
• Cloudflare Skills —— 为 Agent 提供 Cloudflare 平台开发知识
• Otty —— Typora 团队推出的原生终端应用

CodexBar

CodexBar 是一个 macOS 菜单栏应用，支持查看 Codex、OpenAI、Claude、Cursor 等服务的 session、weekly、monthly 窗口和 reset 倒计时。README 当前列出 63 个 provider，准备开始长任务前，可以先看一眼还有多少额度。

它还支持服务状态、credits 和部分花费统计。CodexBar 会复用已有的 OAuth、API key、browser cookie 或本地文件；启用浏览器 cookie 时，macOS 可能会询问 Keychain 或 Full Disk Access，使用前按需打开 provider 即可。

Pane

Pane 是一个 Windows 托盘应用，用来查看 Claude、Codex、Cursor、Copilot 等服务的额度、重置时间和本地花费。它会读取本机已有的 CLI 或编辑器登录状态，找到对应工具后再显示卡片。

Pane 还会根据消耗速度推算能否撑到下一次 reset，并在额度接近用完时发送 Windows 通知。它分析本地日志并结合模型价格估算花费，没有公开价格的模型只保留 token 数量，重要账单仍然以服务商后台为准。

ai-agent-book

《深入理解 AI Agent：设计原理与工程实践》 是李博杰开源的 Agent 技术书，包含中文正文、编译好的 PDF 和按章节组织的配套代码。

全书共十章，从 Agent 基础、上下文工程、记忆、MCP 和工具设计，一直写到 Coding Agent、评估、多模态和多 Agent 协作。书中用“Agent = LLM + 上下文 + 工具”概括 Agent 的组成，也提供了 agent-skills-ppt 等可以继续动手的示例，适合边读边跑。

grok-build

grok-build 在线书 以 xAI 开源的终端 AI Coding Agent Grok Build 为主线，从 Rust 源码拆解 agentic loop、上下文压缩、工具系统、沙箱隔离、终端增量渲染和扩展生态，并对照 Codex 与 OpenCode 的实现。

配套的 ZhangHanDong/grok-build 源码仓库包含 75 个 crate。书中架构结论都带有 file:line 引用，也提供按 Agent 内核、工具与安全、终端 UI、扩展平台划分的阅读路径，适合想理解 Coding Agent 内部结构的人。

TanStack Intent

TanStack Intent 是 TanStack 用来发布和消费 Agent Skills 的 CLI 与配套机制。

你在 React Query（现在的 @tanstack/react-query）node_modules 里看到的 Agent 文档，就属于这套机制：Skill 以 SKILL.md 的形式跟随 npm 包发布，Agent 可以从项目依赖中发现并加载与任务匹配的文档。这样，库的使用规范会跟着版本更新，不必一直依赖模型记忆或手工维护一份旧说明。

cnfast

cnfast 是一个兼容 tailwind-merge 的 cn 工具，可以合并和整理 Tailwind CSS class，并保持与原工具一致的输出结果。它支持从现有的 clsx、classnames 或 tailwind-merge 项目迁移。

项目基准测试显示，cnfast 在多种场景下平均比 tailwind-merge 快 3.8 倍，重复渲染时提升更明显。对于频繁重新渲染的组件、数据表格或实时界面，这类小工具可以减少 class 合并本身带来的开销。

Sticker Forge

Sticker Forge 是一个基于 WebGL 的互动贴纸生成器，可以输入文字或上传图片，再用鼠标把贴纸撕起来，看到卷曲、阴影和贴纸背面的立体效果。

项目同时提供可直接使用的 Web Component 和 JavaScript API，适合放进产品落地页、作品展示或需要一点互动感的网页里。它的重点不是生成一张静态贴纸，而是把“撕开”这个动作做成了可复用的交互组件。

Canvas UI

Canvas UI 是一个开源的 Canvas 和 WebGL 组件库，提供粒子、液态、玻璃、碎裂和 VHS 等视觉效果。组件通过 shadcn CLI 复制到项目中，代码留在自己的仓库里，不需要额外安装运行时包。

它支持 React、Solid、Preact、Vue、Svelte 和原生 TypeScript，适合给网页首屏、作品展示或交互页面增加动态效果。对希望直接拿源码调整，而不是引入一套黑盒动画库的人比较方便。

Takumi

Takumi 是一个用 Rust 编写的渲染引擎，可以把 JSX、HTML 或节点树转换成 PNG、JPEG、WebP、SVG、GIF、APNG 和视频帧，不需要启动 headless browser。

它兼容 next/og 的 ImageResponse API，支持 Node.js、Cloudflare Workers、浏览器和 Rust，也覆盖 CSS Grid、伪元素、渐变、Tailwind utilities 等常见能力。适合生成 OG 卡片、社交分享图、文档图片或动画素材。

Kinetics

Kinetics 是一个基于 spring physics 的网页交互动效库，收集了按钮、卡片、Tab、拖拽、提示框、光标轨迹等 117 个可直接参考的效果。

每个效果都提供 CSS、React 和可复制的 AI prompt，并显示 stiffness、damping 等参数。想给页面加一点有重量感的反馈，可以先从这里挑一个效果，再把代码和参数复制到自己的项目里。

Cloudflare Skills

Cloudflare Skills 是 Cloudflare 提供的一组 Agent Skills，覆盖 Workers、Agents SDK、Durable Objects、Sandbox SDK、Wrangler、Web Performance 和 MCP Server 等开发场景。

如果经常让 Agent 编写 Cloudflare 项目，可以把它当成一套现成的上下文资料，让 Agent 更准确地处理平台 API、部署方式和常见架构。项目兼容支持 Agent Skills 标准的工具，包括 Claude Code、OpenCode、Codex 和 Pi。

Otty

Otty 是 Typora 背后的 appmakes 团队推出的原生终端应用，目前提供 macOS Apple Silicon 和 Intel 版本，Windows、Linux、iOS 版本可以加入等候名单。

它支持 tabs、splits、session recovery、命令面板、inline autocomplete 和长任务通知，也为并行运行多个 Claude Code、Codex 等 Agent 提供任务监控、会话历史、Prompt Queue 和输出回传。适合想保留终端的键盘操作，又需要管理多个 Agent 会话的人。

最后

细节的打磨是优秀产品与普通产品的重要分界线。希望本期分享的内容能为你带来一些新的思考和启发。

感谢阅读本期周刊，我们下期再见。

最近我在写公众号文章的时候，又被代码块折磨了一次。

事情是这样的，文章里只是想放一段配置示例，让读者知道某个 API 怎么调用。电脑上预览还好，代码块有等宽字体，有缩进，也能横向滚动。可是一到手机上，体验立刻变得很差。

读者要么看到一行代码被压得很窄，换行以后缩进全乱；要么需要左右滑动，一不小心又把整篇文章带着动。

我自己作为作者也很痛苦。写文章的时候，代码不是为了让读者复制粘贴一大坨。

很多时候，它只是一个视觉证据：这里确实有一个参数、一个调用方式、一个配置片段、一个关键 diff。

读者需要的是一眼看懂结构，而不是在手机上和横向滚动条搏斗。

所以我最近试着做了一件事：把文章里的关键代码转成图片。

不是所有代码都转。需要复制的完整代码，还是应该放链接、仓库、Gist 或文档页。但在公众号正文里，那些用来解释、展示的代码片段，图片反而更适合阅读。

读者在阅读的时候，通常不会需要复制代码。

代码图片解决的不是“好看”

很多人第一次听到“代码转图片”，会以为它只是让代码变漂亮。

当然，漂亮是有用的。公众号文章本来就是移动端阅读场景，图文排版、留白、色彩、层级都会影响读者愿不愿意继续往下看。

但我真正关心的不是装饰感，而是阅读稳定性。

代码变成图片以后，移动端至少有几个变化：

• 缩进不会被微信编辑器重新解释；
• 长行不会在奇怪的位置硬折断；
• 主题、行号、语言标识可以保持一致；
• 读者不需要左右滑动代码块；
• 作者可以控制图片宽度、留白和背景，让它和正文节奏更合拍。

这对技术文章尤其明显。

比如我写一段 JSON 配置，如果直接贴在公众号里，手机上一换行，层级感就没了。读者原本只需要看 model、tools、messages 之间的关系，结果注意力全被滚动操作占掉。

如果把它转成一张清晰的图片，读者就能像看截图一样扫过去：先看整体结构，再看重点字段。它虽然适合复制，但非常适合理解。

怎么取舍？

正文讲解用图片，完整可复制代码放链接。

也就是说，如果这段代码承担的是“解释”和“展示”的任务，我会把它转成图片；

如果它承担的是“交付”和“复用”的任务，我会给 GitHub、文档页、npm 包、完整示例仓库，或者在文末补一个可复制版本。

比如这些场景很适合代码图片：

• 展示一个 API 请求长什么样；
• 展示某个配置文件的关键字段；
• 展示重构前后的差异；
• 展示 CSS、SQL、正则这种需要语法高亮的片段；
• 展示 Agent 生成的结果摘要；
• 展示“这一段就是问题所在”的代码证据。

这些场景则不适合只放图片：

• 教程里要求读者照着运行的完整代码；
• 很长的源码文件；
• 需要复制的命令；
• 读者可能需要搜索、改写、粘贴到 IDE 的内容。

所以代码图片不是替代代码文本，而是增强读者阅读体验的可选方案。

这就是我做 Codia 的原因

Codia 是我做的一个小工具，目标很直接：把源代码生成适合人阅读、也适合 API 调用的代码图片。

它不是一个只给网页点点点用的小玩具，也不是只能在本地跑的截图脚本。它同时提供了几种入口：

• Playground：在浏览器里粘贴代码，调语言、主题、图片格式、背景、留白、宽度、行号，然后复制或下载图片；
• POST /v1/code/render API：用 JSON 请求生成代码图片，适合脚本、服务端、自动化流程；
• /docs 和 /api/docs：给人看的 API 文档和 OpenAPI 文档；
• /llms.txt：给 Agent 看的说明入口；
• MCP：让支持 MCP 的 Agent 直接调用 render_code_image 或 render_code_image_advanced。

如果你只是偶尔写文章，最简单的方式就是打开 Playground。

把代码粘进去，系统会自动识别语言，比如 typescript、javascript、python、go、json、css；

再选主题、格式、宽度、行号和背景。调到适合公众号正文的宽度后，直接下载图片，插到文章里就行。

如果你已经有自己的写作流程，Codia 更有意义的地方在 API 和 MCP。

手动用法：打开 Playground

最简单的工作流是这样：

1. 写文章时先把代码片段留在 Markdown 里；
2. 发布前挑出真正需要展示的代码；
3. 打开 Codia 的 playground 页面；
4. 粘贴代码，选择语言和主题；
5. 调整各种生成图片的参数，使其满足自己的喜好
6. 复制或者下载图片，放回公众号文章。

公众号里我一般会更关注三个参数。

API 用法：把生成图片变成固定步骤

如果你经常写技术文章，就不应该每次都手动调。

在使用 API 之前，只需要用户登录一下 Chrome 账户，再生成自己的凭证放在请求头里即可！

Codia 提供 POST /v1/code/render，可以从 JSON 生成图片。一个最小请求大概是这样：

curl -X POST http://localhost:4300/v1/code/render \
  -H "content-type: application/json" \
  -d '{
    "language": "typescript",
    "theme": "dracula",
    "format": "png",
    "code": "console.log(\"hello codia\")",
    "containerWidth": 600,
    "borderSize": 12,
    "showLineNumbers": true
  }'

默认返回 JSON，里面有 dataUrl、imageBase64、图片元数据和 recordId。如果设置 responseType: "image"，可以直接拿到图片二进制。Pro/Admin 用户还可以用 responseType: "cdnUrl"，把图片上传到配置好的 R2/S3 兼容存储里，直接拿 CDN URL。

这样一来，代码图片就可以进入工作流，而不是停留在“我打开网页手动做一张图”。

比如你可以写一个小脚本，扫描文章里的代码块，把带有特殊标记的代码块发给 Codia，然后把返回的图片地址插回 Markdown。

我很喜欢这种方式，因为它把审美变成了一个稳定步骤：主题、宽度、留白、行号规则都固定下来。以后每篇文章里的代码图看起来是一套系统，稳定性大大提升。

Agent 用法：让 AI 写文章时顺手出图

Codia 还提供 MCP，这个对我自己的写作特别有用。

现在很多文章我会让 Agent 参与：整理资料、改结构、补示例、做发布前检查。以前让 Agent 处理代码图片很麻烦，它得知道 API 怎么调用、图片怎么保存、哪些参数适合文章。

有 MCP 以后，Agent 可以直接调用工具。

Codia 里有两个主要工具：

• render_code_image：适合常见场景，参数比较少，可以选 github、twitter、docs、blog、glass、macos、minimal 这些 preset；
• render_code_image_advanced：适合精细控制，可以设置完整渲染参数，比如 theme、bgColor、borderSize、containerWidth、showLineNumbers 和 quality。

这意味着我可以在写作任务里直接说：

把文中这三段代码生成适合公众号正文的代码图片，JSON 配置用 docs 风格，TypeScript 示例用 blog 风格，图片宽度控制在 600 左右，保留行号。

Agent 就不需要再“理解图片生成原理”，它只要调用 Codia 的工具，把结果放进文章资产流程里。

工具越适合 Agent 调用，写作流程就越容易自动化。尤其是公众号文章这种有固定生产节奏的内容：选题、资料、正文、配图、代码图、封面、排版、草稿，每一步都可以慢慢沉淀成 workflow。

我现在会放进哪些工作流

第一个是公众号写作。

我会在 Markdown 里保留原始代码，发布前让 Agent 判断哪些代码适合图片化。短配置、关键 diff、核心 API 示例转成图片；需要复制的命令保留文本，并给出仓库或文档链接。

第二个是项目文档。

文档正文里有些代码是为了精读，有些只是为了“长这样”。后者很适合转成图片，尤其是 README、产品介绍页、更新日志、社交平台分享图。Codia 的 API 可以让这些图保持统一风格。

第三个是 AI 工作日志。

比如让 Agent 总结一次重构，它可以把关键代码片段、前后对比、配置变化生成代码图片，再配上文字说明。这样分享给团队或发到文章里，比贴一堆 Markdown code block 更容易被读完。

第四个是发布流水线。

如果你的文章本来就从 Markdown 进入某个发布系统，可以在构建阶段做一件事：识别带标记的代码块，调用 Codia 生成图片，上传到图床或 CDN，再把图片 URL 写回最终稿。

像这样给代码块加一个约定：

```ts
const message = "hello codia"
console.log(message)
```

真正发布前，脚本或 Agent 把它变成一张图。原始代码仍然留在仓库里，公众号看到的是图片。

这个思路的好处是，作者不用在写作时打断心流。写的时候还是写 Markdown，发布的时候再统一处理。

不要滥用

代码图片也有代价。

它不能被读者直接复制，搜索引擎也不容易理解图片里的代码，屏幕阅读器体验也会下降。如果一篇教程全是代码图片，那对真正想跟着做的读者并不友好。

所以建议它当成“展示层”，不是“源码层”。

比较理想的做法是：

• 正文里放代码图片，保证移动端阅读顺滑；
• 文末放完整仓库、文档或可复制代码；
• 图片 alt 或上下文说明里写清楚这段代码展示的是什么；
• 长代码拆短，只展示关键部分；
• 不把图片当成唯一的信息来源。

技术内容最终还是要对读者负责。好看的代码图可以降低阅读门槛，但不能牺牲可访问性和可复现性。

最后

公众号是一个很典型的移动端阅读场景，而代码天生更适合横向空间。

该复制的地方，给文本和链接；该阅读的地方，给一张稳定、清晰、有层次的图片。作者少一点排版焦虑，读者少一点手机上左右滑动的烦躁。

Codia 目前就是围绕这个需求做的：给人一个 Playground，给程序一个 API，给 Agent 一个 MCP。你可以手动用，也可以把它接进自己的写作、文档和发布 workflow 里。

Codia 也是我第一个比较完整的个人作品，目前任然处于早期开发阶段，欢迎大家试用看看！

如果 AI 一天生成 5000 行代码，你会怎么做？

坐下来，从第一个函数开始读，读到最后一个括号？还是先看整体的设计、跑测试、观察程序的运行行为，只有遇到可疑的地方才打开具体实现？

Redis 创作者 antirez 最近给出了一个相当激进的答案：很多开发者没有真正发挥自动编程的能力，原因就在于他们还在看代码。

“看代码”正在变成瓶颈？

2026 年 7 月 12 日，antirez 发了一条很容易引发争论的推文：

It is my belief that many devs right now are not maximizing what they can do with automatic programming because they still look at the code. Doing it makes you the bottleneck. Your time is better invested in new ideas, QA, design, and asking yourself what is your goal.

大意是：“亲自做这件事，会让你成为瓶颈。你的时间更应该投入到新想法、质量验证和设计上。”

这条推文的文字记录显示，它获得了超过 2500 个点赞，超过 149 万阅读量。antirez 的意思很明确：如果 AI 已经可以持续生成代码，开发者还把大量时间花在逐行阅读上，自己的时间就会被代码生产速度拖住。

这个观点听起来像是在说， AI 写代码超快，程序员反而是拖慢整体速度里，木桶最短的那一块。

我们花了这么多年学习语法、数据结构、并发、内存和各种框架，最后却有人提出这样的建议：代码最好少看一点？

他真正反对的，可能是“默认逐行审查”

antirez 后来在博客里写了《控制思想，而不是代码》，把这件事完整解释了一遍，有兴趣的读者朋友可以去看看。

首先，他并没有建议大家随便写一句提示词，然后等着 AI 交付一个软件。相反，他认为大语言模型 在“局部实现”上已经很强，真正容易出问题的地方往往在更大的设计上：

• 数据结构是否选对；
• 模块之间的关系是否合理；
• 性能目标是否清楚；
• 边界条件有没有被设计进去等等；

他认为如果这些事情没有想清楚，开发者就算把生成的每一行代码都读完，也可能只是认真检查了一条错误的路线。

打个比方，这就像拿着放大镜检查一座桥的每颗螺丝，却没有先问桥要承受多少重量、建在哪里、遇到洪水怎么办。螺丝当然要检查，可它们不是整座桥的设计。

antirez 认为，开发者更应该维护一份清晰的设计文档（DESIGN.md），用人类语言写明每个数据结构的设计、实现技巧和关键取舍。以后有人要修改有序集合，不必先在几千行代码里游泳，而是先读懂设计，再让智能代理按照这个心智模型工作。

这里的重点不在于“代码不重要”。重点在于：代码应该从主要阅读对象，变成验证设计是否落地的一种证据。

antirez 自己也没有真的完全不看

他在博客里承认，自己仍然会检查人工智能生成的 Redis 代码。他参与了 Redis 数组功能的实现，也在做 序集合的内存优化，提到后者可能带来 50% 的内存节省。

他会修改自己不喜欢的写法，也会寻找细小的设计问题。

那他为什么还要说逐行审查“基本没用了”？

他的解释是：Redis 是很多人依赖的公共软件，用户会直接打开源码、修改源码，所以他继续检查代码，更多是出于对用户负责。如果只考虑自己的效率，他宁愿把审查时间拿去做质量保证、想下一步优化，或者补充设计文档（DESIGN.md）。

也就是说，antirez 的观点并不是“代码永远不用看”，而是“逐行看代码不应该再成为所有项目的默认动作”。

对于一个个人工具、一次性的脚本、风险很低的内部功能，逐行阅读可能确实是在浪费时间。对于 Redis 这种基础设施软件，内存、并发、兼容性和错误处理都可能影响大量用户，自然会更谨慎。

Redis 数组功能的开发过程，也没有那么“放手”

antirez 介绍 Redis 数组功能 开发过程的另一篇文章里，反而能看到大量人工参与。

他先花了一个月写规格文档，明确数据结构、稀疏表示、游标语义和操作方式。之后才和 大语言模型 来回讨论设计，再进入实现阶段。代码完成后，他持续检查、重写模块、做压力测试，确认实现足够可靠。

这和“完全不读代码”之间，隔着很长一段距离。

也许更准确的说法是：人要把时间从“平均分配给每一行代码”，改成“集中在最值得怀疑的地方”。

如果一个模块处理内存分配、锁、权限、支付金额或用户数据，那些关键路径当然值得读。可是一个已经被类型系统、单元测试、集成测试和压力测试反复验证的局部实现，是否还值得人工从头扫到尾？

这个比例该怎么分配，没有一个统一答案。

代码质量，真的只取决于有没有人工看过吗？

很多人反对 antirez，而且反对的人还不少，很多人担心的是软件质量。

这个担心很合理。AI 可以生成一段看起来完整的代码，也可以顺手写一组看起来完整的测试。问题是，测试本身可能漏掉了关键场景，代码和测试还可能共同建立在一个错误的理解上。

但是，“我看过每一行”也不等于“我理解了整个系统”。

反过来，完全不看代码也有问题。你怎么知道设计文档（DESIGN.md）中的设计真的被实现了？如果文档漏掉了一个锁的顺序、一个整数溢出条件，或者一个异常路径，谁来发现？

代码有时候像建筑的施工现场。设计图能告诉你房子想怎么建，但墙里有没有少几根钢筋，总不能永远靠设计图推断吧？

所以，真正影响 AI 代码质量的因素，可能至少包括：

• 模型本身的能力；
• 任务范围是否清晰；
• 代码库是否容易理解；
• 设计文档有没有写到关键取舍；
• 智能代理 有没有足够的工具和上下文；
• 测试、质量保证、监控和回滚是否可靠；
• 这段代码出错后，会不会带来严重后果等等。

在一个干净的小项目里，AI 可能给你一个很好的结果。在一个历史包袱很重、边界条件很多的系统里，同样的模型可能会把问题越改越深，把一切搞砸。

把两种情况用一句“以后不要看代码”按下，显然有点扯淡。

Uncle Bob：用约束代替逐行阅读

这也让我想到 Uncle Bob Martin 最近表达的另一个真实策略。他的做法比“少看代码”更激进：他甚至不读 智能代理 写出的代码，而是把 智能代理 放进一整套极端约束里。

他说:

中文翻译：我六十年代末就开始写代码了。我现在的策略是不阅读智能代理写出的任何代码。只有这样，我才能真正利用它们的生产力。我的做法，是给智能代理套上极其严格的约束：单元测试、场景测试、质量保证流程、质量指标、变异测试、测试覆盖率，以及许多其他检查。最终，我对它们生成的代码有很高的信心，因为这些代码必须闯过我设置的所有约束和测试。

他的答案和 antirez 的判断有一个重要差别：antirez 更强调人应该控制设计、心智模型和关键判断；Uncle Bob 则进一步把“信任”外包给一套必须通过的测试与质量门槛。代码不需要被人平均阅读，但必须在单元测试、场景测试、质量保证流程、质量指标、变异测试和测试覆盖率等约束下闯过一轮又一轮检查。

这补上了“不要逐行看代码”最容易被忽略的另一半：不读代码不等于不控制代码。人的控制权从每一行实现，移动到了约束条件、测试场景和验收标准。

当然，约束本身也不是魔法。如果测试漏掉了关键场景，或者场景描述写错了产品意图，智能代理 依然可能很高效地通过一套错误的考试。所以，开发者仍然要负责设计这些约束，确认它们测的是正确的问题，而不是只看最后的结果。

社区争论，其实很有代表性

这篇文章在 技术社区的讨论里很快分成了几种声音。

有人认同 antirez 的判断，认为开发者真正应该花时间做架构、写规格、设计测试和思考产品方向。代码已经多到读不完，继续坚持逐行检查，只是在维护一种旧的职业习惯。

也有人提出反问：

如果一个人没有通过写代码、读代码和处理 缺陷 建立心智模型，他凭什么只控制“想法”？设计文档（DESIGN.md）也可能写得很漂亮，却遗漏了真实实现中的细节。更年轻的程序员尤其需要通过实际编码，慢慢获得判断设计好坏的经验。

还有一种意见我觉得很值得注意：代码审查本来就不应该等于审查所有代码。很多开发者会选择重点查看公共 接口、关键数据结构、并发逻辑和高风险路径，把其他部分交给测试与自动化工具。

这可能更接近大多数团队现在能落地的方式。

从代码工匠变成系统的掌舵者？

antirez 想推动的，也许是一种工作身份的变化。

过去，程序员像工匠一样亲自加工每个零件。代码是一行一行写出来的，理解系统也常常从阅读这些代码开始。

现在，AI 可以加工大量零件，而且速度极快。打个比方，程序员更像航海船长：决定船往哪里开，规定不能驶入哪些海域，设置仪表盘，安排测试，在风浪里判断是否返航。

但这个比喻也有一个危险的地方。

船长不能因为自己不亲手焊接发动机，就完全不懂发动机。否则仪表盘坏了，船偏离航线时，他可能连问题发生在哪里都不知道。

所以问题远远比我们想象中的复杂，在这个 AI 快速发展的时代，现在留下的定论也许很快就会被推翻，一切变得扑朔迷离，难以捉摸...

也许应该把它当成一个实验

antirez 的话之所以有冲击力，是因为他说得很绝对。

绝对的表达容易传播，也容易让人站队。但真正落到项目里，变量太多了：项目规模、代码质量、模型能力、测试体系、开发者经验、失败成本，都会改变答案。

也许我们现在应该尝试的是：

先写清楚设计，再让 AI 实现；用测试、质量保证、类型系统和运行结果去验证；人工重点检查公共接口、关键路径和高风险的核心逻辑。

至于普通的局部实现，逐行阅读可以从“必做动作”降级为“发现异常时再做”。

这不一定适合每个人，也不一定适合每个项目。

无论如何，这个问题值得我们每一个开发者思考：

当 AI 生成代码的速度已经超过我们阅读代码的速度，开发者还要把一天的时间平均切成两半，一半用来产生新想法，一半用来追赶 人工智能 生成的文本吗？

也许我们真正需要重新设计的，不是代码审查本身，而是“什么值得审查”。

写到这里，我自己也有点迷糊了，让子弹再飞一会吧！

shimmer text 是一种很常见的 CSS 文字高亮扫光效果：文字本身不动，一条亮色渐变从字形里扫过去，让它看起来像被光擦了一下。

你可能在 loading 文案、AI 正在生成的提示、产品首页 hero、价格标签里都见过它。效果很小，但如果写得舒服，页面会多一点“正在运行”的感觉。

现在 AI 已经能帮我们生成很多代码了，但我反而更觉得，一些基础技术还是值得自己弄懂。至少要做到**知其然！**看到一个 CSS 动效时，知道它大概由哪些属性拼起来，出了问题也知道从哪里拆。

所以这篇先不急着贴页面和仓库。我会先一步步拆 shimmer text 的原理：渐变怎么做出来，为什么能裁进文字，背景为什么要移动，倾斜高亮为什么还要算安全距离。

专门的教程页面和源码仓库我放在文末，读完原理以后再打开看，会更顺。

这个效果叫什么

一般可以叫它：

• shimmer text
• text shimmer
• gradient text shimmer
• 或者更直白一点：文字高亮扫光效果

它经常出现在这些场景里：

• loading 状态里的文字或骨架屏；
• AI 产品里“正在生成”的提示；
• 首页 hero 里的重点短句；
• 产品价格、功能标签、活动入口里的强调文案；
• 需要一点“正在运行”感觉的交互界面。

我个人会比较克制地用它。

因为 shimmer 很容易从“有质感”滑到“过度动效”。如果整个页面到处都在闪，用户的注意力会被拖着走，阅读会变累。我的倾向是：只在一个短句、一个状态、一个核心 CTA 周围使用它。

先一步步拆开原理

先把页面和工具放一边，单看这个效果本身。

它背后其实有三层东西：

• 文字本身；
• 一张比文字更宽的渐变背景；
• 把背景裁剪进文字形状的 background-clip:text。

这张图基本就是它的工作方式：小黑在后面推一条高亮带，文字像窗口一样，只露出背景穿过字形的那一部分。

第一步：先做一条静态高亮背景

先不考虑文字，也不考虑动画。

我们只需要一条渐变：

-- language: css --

.shimmer {
  background-image: linear-gradient(
    80deg,
    #8a8a8a,
    #ffffff,
    #8a8a8a
  );
}

这一步只是准备材料。

#ffffff 是最亮的高光，左右两侧的灰色负责让它过渡得自然一点。shimmer 的质感，通常来自这个亮区的宽度：太宽会像一大片灯扫过去，太窄又会显得硬。

在 demo 里，我把高亮宽度做成了可调参数。这样读者可以直接看到：高亮区域越窄，效果越像一道光；高亮区域越宽，效果越像一块亮背景。

第二步：把背景裁剪进文字

这里进入关键 CSS：

-- language: css --

.shimmer {
  color: transparent;
  background-image: linear-gradient(
    90deg,
    #ff4d6d,
    #ffd166,
    #06d6a0,
    #4cc9f0,
    #8a5cf6
  );
  background-clip: text;
  -webkit-background-clip: text;
}

这里有三个点要一起看：

• color: transparent：把原本的文字填充色藏起来；
• background-image：给文字背后放一张背景；
• background-clip: text：只在文字字形范围里显示背景。

这时候读者看到的“字”，其实是背景图透过字形露出来的区域。

这里也有一个小坑。

如果你前面已经设置了 background-clip:text，后面又写了一次 background: ...，background 这个 shorthand 可能会把一些 background 相关属性重置掉。为了少踩坑，我更推荐在这个效果里使用 background-image，再单独写 background-size、background-position。

第三步：让背景比文字更宽

如果背景和文字一样宽，动画空间会很紧。

高亮带刚开始移动，就可能已经压在第一个字母上了。restart 的时候尤其明显：你以为动画会从最左侧外面进入，结果高亮一刷新就贴在文字上。

所以 demo 里用了：

-- language: css --

.shimmer {
  background-size: 400% 100%;
}

意思是：背景的宽度是文字可见区域的 4 倍。

这样高亮可以从文字左侧外面进入，穿过文字，再从右侧离开。文字本身不动，动的是这张更大的背景。

第四步：动画移动 background-position

动画部分其实很短：

-- language: css --

.shimmer {
  animation: shimmer var(--speed) ease-in-out infinite both;
}

@keyframes shimmer {
  0% {
    background-position: var(--start-position) 0;
  }

  72%,
  100% {
    background-position: var(--end-position) 0;
  }
}

重点是 background-position。

0% 是背景起点，72% 到 100% 是收尾段。后面留一点时间不继续移动，动画循环时会更稳，不会像机械循环一样马上跳回来。

这个处理很小，但体感明显。

我在 demo 里还加了 pause、restart 和 speed 控制。它们方便观察参数变化：当速度变慢、角度改变、宽度收窄时，背景移动的边界会变得更容易看出来。

第五步：为什么要算 safeDistance

做到这里，普通 shimmer 已经能跑了。

让我多花时间的是这个问题：

点击 restart 时，怎样让高亮真的从文字外侧进入？

如果高亮是水平的，事情还算直观。多留一点左右距离就行。

但这次我们希望高亮是 45deg 倾斜的。倾斜以后，高亮带会因为文字高度产生额外横向投影。说得直白一点：同样一条斜线，要保证它完全不碰到文字，就要比水平情况多留一些距离。

于是 demo 里算了一个 safeDistance：

-- language: js --

const angle = 45 * Math.PI / 180

const safeDistance =
  (shineWidth + textHeight * Math.abs(Math.cos(angle)) / 2)
  / Math.abs(Math.sin(angle))

这里不用把它想得太复杂。

我们只是根据：

• 高亮带宽度 shineWidth；
• 文字高度 textHeight；
• 高亮角度 angle；

算出一段额外的水平移动距离。

demo 里蓝色虚线和黄色安全范围就对应这个关系：蓝色范围表示文字可见区域，黄色范围表示高亮为了完整进出，需要额外走过的区域。

如果你把角度调得更斜，或者把高亮宽度调得更大，安全距离就会变大。这个关系可以用三角函数解释，实际工程里把它封装成一个计算函数就够了。

最小版本可以这样写

一份比较完整的最小版本大概是这样：

-- language: html --

<p class="shimmer">CSS is awesome, right?</p>

<style>
  .shimmer {
    --speed: 2.4s;
    --angle: 45deg;
    --shine-width: 120px;
    --start-position: 72%;
    --end-position: 28%;

    display: inline-block;
    color: transparent;
    font: 700 48px/1.1 system-ui;
    background-image: linear-gradient(
      var(--angle),
      #8a8a8a calc(50% - var(--shine-width)),
      #ffffff 50%,
      #8a8a8a calc(50% + var(--shine-width))
    );
    background-size: 400% 100%;
    background-position: var(--start-position) 0;
    background-clip: text;
    -webkit-background-clip: text;
    animation: shimmer var(--speed) ease-in-out infinite both;
  }

  @keyframes shimmer {
    0% {
      background-position: var(--start-position) 0;
    }

    72%,
    100% {
      background-position: var(--end-position) 0;
    }
  }
</style>

如果只想做一个静态展示，这些就够了。

如果想像 demo 一样支持角度、宽度、restart、pause，就需要再加一点 JS，动态更新 CSS 变量。我的建议是：先把 CSS 版本跑通，再做控制器。不要一上来就把调参面板、localStorage、教程轮播全塞进去。

我会注意的几个细节

这个效果写起来不难，影响质感的是细节：

• 高亮不要太宽：短句里 2 个字母左右通常比较舒服。
• 角度不要乱跳：45deg 很稳定，识别度也好。
• 背景要足够大：background-size: 400% 100% 是一个好起点。
• restart 要从外面进：不要只重置动画，还要确认 start-position 真的在文字外。
• 正文阅读场景慎用：长段落一直闪，读者会累。

我个人觉得，shimmer text 最适合放在“状态变化”附近。

比如 AI 正在生成、模型正在思考、结果即将出现。它传达的是一种轻微的进行中状态。放在纯装饰场景里也能看，但容易喧宾夺主。

最后

这个小 demo 对我来说有一个挺有意思的点：很多 CSS 动效看起来像视觉技巧，拆开以后其实是几个很朴素的概念在配合。

linear-gradient() 做材料，background-clip:text 做裁剪，background-position 做移动，再用一点几何计算处理边界。

读者如果只想拿走一个结论，我会建议记住这句：shimmer text 的文字通常不动，动的是文字背后的背景。

先写到这里。后面如果我继续把这个 demo 做成更完整的 CSS 小课，可能会再补一篇，专门聊“如何把视觉效果做成可学习的交互说明”。

相关链接

专门的教程页面在这里：

CSS Shimmer Text Demo

源码也放到了 GitHub：

AaronConlon/shimmer-text-demo

这个页面一开始只是想复刻一个文本闪光效果，后来越做越像一个小教学工具：可以调速度、调高亮宽度、调角度，可以看完整背景，也可以看文字可见范围和计算后的安全范围。

上篇我们从 React Query 出发，走到了 TanStack 的产品矩阵。本篇继续往下看：当它面对 SWR、RTK Query、Apollo、React Router 和 Next.js 等方案时，究竟把复杂度放在了哪里；公开 Issue 又如何暴露它的优势与代价。

和前端竞品放在一起看

比较工具时，最容易陷入“谁的 API 更漂亮”，但这种看法非常主观，千人千面，很多时候谁也说服不了谁。更实用的方式是看它们把复杂度放在哪里。

数据请求：SWR、RTK Query、Apollo 与 TanStack Query

SWR 的优势是轻量和直接，适合希望用较少抽象实现缓存与重新验证的项目。它的心智模型清楚，和 React 组件组合自然。TanStack Query 的范围更大，除了查询缓存，还把 mutation 生命周期、离线、持久化、开发工具和多框架适配纳入体系。项目越复杂，后者的统一性越有价值；项目越简单，SWR 的轻量可能更舒服。

RTK Query 与 Redux Toolkit 绑定得更紧。如果团队已经把 Redux 作为全局状态中心，RTK Query 可以让接口数据进入同一套 store、middleware 和规范中。TanStack Query 则坚持把服务器状态从客户端 store 中分离出来。两者没有绝对高下，区别在于团队是否希望所有状态共享一套 Redux 基础设施。

Apollo Client 解决的是更明确的 GraphQL 场景：它会围绕 schema、实体缓存和查询文档建立一整套客户端模型。拿它直接和 TanStack Query 比，容易忽略数据协议的差异。TanStack Query 更像通用的异步状态层，Apollo 则更像 GraphQL 应用的专用客户端。

路由与全栈：React Router、Next.js 与 TanStack Router

React Router 的优势是生态广、历史长、团队认知成本低，并且已经覆盖数据路由与框架模式。TanStack Router 的差异在于类型安全更彻底：路由树、路径参数、搜索参数和 loader 数据之间的关系，尽量在编译阶段暴露问题。

Next.js App Router 则是更完整的应用框架，服务端组件、部署平台和约定式工程能力都更成熟。TanStack Router 与 Start 选择的是更可组合、更靠近 Vite 和运行时的路线。前者适合希望快速获得完整平台的团队，后者适合希望保留更多基础设施选择权、并把路由和数据流作为核心设计的团队。

这个选择也对应 TanStack 的长期风险：类型安全与可组合性越强，学习曲线和类型复杂度越高；框架越年轻，生态和文档稳定性就越需要时间验证。

表格：AG Grid、MUI Data Grid 与 TanStack Table

AG Grid 和 MUI Data Grid 更强调完整组件体验，适合希望快速得到排序、筛选、分页、编辑和主题能力的团队。TanStack Table 把渲染层留给应用，因此能适配更多设计系统，但也把无障碍、键盘行为、空状态和性能细节交还给开发者。

换句话说，TanStack Table 的“自由”不是免费的。它的价值不在于让所有项目都少写代码，而在于当产品需要特殊的交互和视觉约束时，底层引擎不会成为天花板。

从公开 Issue 看团队如何处理问题

开源项目真正的工程能力，往往要到问题发生时才看得出来。TanStack 的 GitHub Issue 有一个很明显的特点：维护者经常不急着把所有反馈都定义成 bug，而是先解释行为背后的模型，再给出迁移方式、临时方案或明确的“不计划支持”。这让讨论不一定总是让提问者满意，但通常能留下可复用的上下文。

Query 的 hydration 争议：正确性优先于旧行为

在 Issue #6240 中，用户反馈 v5 的 HydrationBoundary 和 v4 的 Hydrate 行为不同：客户端切换页面时，缓存数据似乎更新得太晚，页面会先使用旧数据渲染。

维护者没有简单把它当作回归修掉，而是解释了这个变化的原因：v4 可能在 React transition 完成前就修改当前页面的缓存，甚至在 transition 被取消后留下可观察的副作用；v5 选择把 hydration 推迟到渲染之后，接受短暂的不完美，以避免在 render 阶段修改外部缓存。对于直接读取缓存但没有建立 observer 的用法，维护者也明确指出这不是推荐模式，并建议使用 useQuery 或自行保留底层 hydrate 方案。

这个案例的价值不在于 v5 一定没有代价，而在于它展示了一种取舍：当 React 的并发模型与旧缓存行为冲突时，团队选择了更容易解释的正确性，并给高级用户留下低层 API。这样的答复比“升级到最新版即可”更有长期价值，但也意味着迁移者需要真正理解数据订阅模型。

浏览器兼容：支持范围就是产品边界

另一个更直接的例子是 Issue #6371。用户在 Safari 14 中升级 Query v5 后遇到私有类字段语法错误。维护者的判断很明确：v5 的支持范围从 Safari 15 开始，Safari 14 不属于默认支持的浏览器；如果项目必须兼容旧浏览器，就让构建工具转译依赖，或者暂时停留在 v4。

这不是一个讨喜的答案，却是一种清晰的工程沟通。团队没有为了覆盖所有环境而牺牲包体积和现代语法，也没有把“浏览器支持”隐藏在实现细节里。开源库的使用者因此可以根据目标用户做选择，而不是在生产环境里才发现隐含条件。

类型变更：修复很快，但兼容策略仍有争议

在 Issue #9660 中，v5.89.0 的 mutation 回调类型发生变化，onSuccess、onError 和 onSettled 的参数位置与类型让一些已有代码无法编译。维护者先解释新增参数与已有上下文的关系，随后提交修复，并继续追问低层封装如何同时兼容不同版本。

这个案例比前两个更能说明 TypeScript 库的现实：运行时没有变化，不代表类型层没有破坏性影响。TanStack 文档把类型修复视为可以随补丁版本发布的变化，这有助于持续改善类型推导，但对构建二次封装的团队并不总是轻松。它的优势是维护者能够快速响应类型问题，代价是升级时需要锁定补丁版本并认真阅读变更。

Router 与 Start：快速迭代带来的基础设施风险

Router 生态中的 Issue #3367 讨论了近期版本的非流式 SSR hydration 问题，Issue 最后指向已有 Discussion，而不是在问题页面里继续堆叠一个孤立修复。这种处理方式体现了项目在把具体故障放回更大的 SSR 讨论中，但对只想得到“哪个版本能用”的使用者来说，信息分散也会增加查找成本。

Start 的问题则更容易触及运行时边界。比如 Issue #7402 记录了持续 SSR 负载下的内存增长：报告者通过压测区分出 QueryClient 的 gcTime 保留和原生流缓冲两个路径，其中一个可以通过 gcTime: 0 缓解，另一个仍需要进一步处理。这个 Issue 后来关闭，但正文保留了复现条件、内存数据和 bisect 结果。

这里能看出 TanStack 和成熟大框架的差异。TanStack 更常把问题拆成可验证的技术假设，鼓励用户提供最小复现和测量结果；它不一定立刻给出一个封装好的答案，但会让问题边界变得清楚。对于早期的全栈框架，这种公开的工程过程很有价值，也提醒使用者：RC 产品不应该被当成已经完成所有生产验证的基础设施。

Table 的重渲染：headless 不等于自动优化

在 Issue #4794 中，用户反馈可编辑表格会出现大量行和单元格重渲染。讨论里出现了 useMemo、拆分并记忆 Row/Cell、避免不稳定的渲染函数等多种方案，后续评论还指出某些 flexRender 用法会导致组件被卸载再挂载。

这件事不能简单归咎于库“性能不好”。TanStack Table 把渲染层交给应用，应用也就必须负责稳定列定义、稳定数据引用、行级记忆和虚拟化策略。headless 的优势是没有固定组件层，代价是性能模型需要由使用者掌握。它适合愿意理解渲染链路的团队，不适合把所有细节都交给组件库的项目。

TanStack 为什么能迅速发展

把这些产品与 Issue 放在一起看，TanStack 的增长并不只是因为某个库碰巧流行，而是因为它形成了几条相互强化的路径。

一套连续的心智模型

Query 用查询键描述数据身份，Router 用路由树描述页面边界，Table 用状态模型描述数据视图。它们都在做同一件事：把隐含在组件和副作用里的关系，变成可以组合、可以观察、可以被类型系统检查的结构。

开发者从 Query 进入后，很容易理解 Router 的 loader、Table 的受控状态和 Virtual 的可见范围。产品之间不必完全绑定，但学习收益可以迁移，这比单纯增加包数量更重要。

Headless 与可移植性

TanStack 不急于提供一套统一视觉组件，而是把核心行为和渲染层拆开。这让它能适配不同框架、设计系统和运行时，也减少了“换一个 UI 库就要重写业务逻辑”的成本。

当然，headless 也会把实现责任交还给应用。TanStack 的强项不是替你做完所有事情，而是让底层模型足够清楚，允许你在不同产品约束下继续组合。

TypeScript 不只是类型提示

在 Router 里，类型系统是路由合同；在 Query 里，它约束查询键、函数返回值和 mutation 参数；在 Table 和 Form 里，它帮助字段、列和表单状态保持一致。类型因此不再只是编辑器里的辅助信息，而成为库设计的一部分。

这也是 TanStack 与一些“运行起来就行”的工具的差异。它愿意把复杂度提前放进类型系统，换取大型项目在重构时更早暴露问题。代价是类型错误可能很长，升级时也更容易遇到补丁版本带来的编译变化。

公开的产品节奏

官网把不同产品标注为 stable、RC、beta 或 alpha，GitHub Issue 里也经常保留设计背景、复现步骤和维护者判断。它没有消除风险，但让风险更可见。

这套节奏还带来一个社区效应：使用者不只是等待一个封闭产品交付，而是可以通过 Issue、Discussion、赞助、文档和示例参与产品形成。对于一个以开源为核心的团队，这种持续的公开反馈比一次性宣传更能积累信任。

TanStack 的野心与展望

TanStack 现在的产品矩阵，已经从“几个好用的 React 库”走向“应用开发中常见边界的一组基础设施”：数据获取、路由、全栈运行、表格表单、性能、开发工具，以及 AI agent 的使用方式。

这种野心有三个方向。

第一，它想把应用状态、URL 状态和服务器状态放进一套可以相互连接的模型里。Query 负责数据缓存，Router 负责页面与 URL，Start 负责服务器边界，三者组合后，应用可以在预取、渲染、流式输出和客户端更新之间减少重复胶水代码。

第二，它想保持基础设施的可替换性。与绑定某个部署平台或 UI 体系相比，核心库、适配器和运行时输出的分层更适合多框架、多运行时的前端世界。这也是它持续强调 framework agnostic、type-safe 和 no vendor lock-in 的原因。

第三，它开始为 agent 时代准备工具链。CLI 和 Intent 目前还不能与 Query、Table 的成熟度相提并论，但它们表达了一个判断：未来的开发者体验，不只是让人更快写代码，也要让自动化工具能理解项目结构、安装能力、遵循约束并完成验证。

不过，TanStack 也必须面对自己的扩张风险。产品越多，版本和文档之间的组合越复杂；Start、AI、DB、Store 等新项目还需要时间证明稳定性；headless 的自由会带来更多应用级责任；类型系统的优势也可能变成学习门槛。

所以，TanStack 的下一阶段不只是继续发布更多项目，而是要证明这些项目组合起来确实比各自为战更好用。如果它能在保持可移植性的同时，进一步降低全栈配置、SSR 调试、状态同步和 agent 使用的成本，那么它就可能从“优秀的开源工具集合”变成前端应用的通用基础层。

最后

TanStack 的崛起，核心不在于它覆盖了多少产品，而在于它一直在尝试用同一套工程原则处理不同层次的问题：明确状态边界、强化类型合同、拆开核心与渲染、公开稳定性和取舍。

从 React Query 开始，它先解决了服务器状态的混乱，再把这套方法延伸到路由、全栈、数据视图与开发工具。未来它能走多远，取决于产品之间的组合是否足够稳定，也取决于这些抽象能否继续给真实项目带来比额外复杂度更多的收益。

感谢阅读这篇文章，我们下期再见。

前端工具的竞争，表面上是 API 的竞争，底层其实是对复杂度的重新分配：哪些事情交给框架，哪些事情交给应用，哪些事情应该由类型系统提前约束。

一个库能不能长期留下来，往往不只取决于它能不能解决一个问题，也取决于它能不能在下一个问题出现时继续保持同一套判断。

今天，让我们一起来了解一下 TanStack 的技术“史诗”！

它最初因为 React Query 被更多开发者认识，后来逐步扩展到路由、全栈框架、表格、表单、虚拟列表、AI 与开发工具。今天的 TanStack 已经不太像一组彼此独立的工具，而更像一套围绕 TypeScript、数据流和应用边界组织起来的前端应用栈。

让我们沿着产品技术栈一步步向前走：React Query 解决了什么，TanStack 为什么要改名，竞品各自把复杂度放在哪里，以及这些公开 Issue 如何暴露出它的优势与代价。

React Query 先解决了什么

在 React Query 出现之前，前端获取数据通常会混合几种工作：组件启动请求、显示 loading、处理错误、保存结果、判断结果是否过期、响应窗口重新聚焦、处理重复请求，以及在修改数据后让相关页面重新获取数据。

这些工作并不难单独完成，难的是它们会在每个页面重复出现。一个页面写一套 useEffect，另一个页面写一套全局状态，最后大家都要回答同样的问题：这份数据现在属于谁？多久算旧？两个组件同时请求同一个资源时，能不能复用结果？修改完成后，哪些缓存需要失效？

这些问题贯穿着 React 项目的方方面面，无论开发者水平是高是低，都需要直接面对这个问题。在一个团队里，给出一份稳定、高效且让大家都满意的方案并不简单。

React Query 的重要变化，是把问题从“如何在组件里发请求”改成“如何声明一份服务器状态”。在今天的 TanStack Query 里，查询键、查询函数和缓存生命周期组成了一个相对完整的模型。

最小的使用方式看起来很简单：

-- language: tsx --

const todosQuery = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

少写几行请求代码价值并不大，这几个概念被固定了下来才是重头戏：

• queryKey 是缓存的身份，也是依赖关系的声明；
• 查询结果可以在组件之间共享，并自动去重；
• 新数据可以在后台刷新，页面不必每次都回到空白 loading；
• mutation 可以和失效、乐观更新、回滚联系起来；
• 缓存、重试、离线和开发调试都有统一入口。

以上功能涉及到了 Web 开发的方方面面，每一个都可以单独拉出来开发一个 npm 包，但是 Tanstack Query 直接给我们提供了一个完整的、强类型的无敌解决方案！

这让“服务器状态”和“客户端状态”开始分开。输入框是否展开、弹窗是否打开，仍然适合交给组件状态或状态管理库；来自接口、会过期、可能被别的用户修改的数据，则应该有自己的缓存和同步机制。

React Query 最早的影响，正是让很多团队意识到：不是所有状态都应该塞进 Redux，也不是所有异步逻辑都应该散落在副作用里。

从 React Query 到 TanStack Query

2022 年发布的 v4 是一次关键转折。官方在 v4 发布文章 中说明，项目从过去的 React 专属库，重构为无框架核心加框架适配器的形式，并开始支持 Vue、Svelte 和 Solid。

这次改名不是简单换一个 npm 包名。它改变了项目的边界：核心缓存、查询客户端、订阅和状态转换尽量不依赖具体 UI 框架；React 的 hook、Vue 的组合式接口，属于上层适配器。这样做有两个直接收益。

第一，维护者可以复用同一套数据逻辑。第二，用户学到的不是某个框架的技巧，而是一套可以迁移的服务器状态模型。v4 还加入了更完整的离线支持、持久化和 React 18 兼容能力，说明它已经不满足于“帮你发请求”，而是在争取成为异步状态的基础设施。

到了 v5，项目继续收紧 API，拥抱更现代的 TypeScript 和 React 并发模型。这种演进方式也埋下了 TanStack 的一个特征：它愿意为了长期模型调整短期兼容性，但会把迁移说明、类型边界和取舍放到台面上讨论，团队开发人员在 github 上发布了大量解释性回复，同时也写了很多实用的教程和博客。

按产品技术栈看 TanStack

上图是 TanStack 当前产品矩阵的一个概览。它的扩张不是简单地“看到什么热门就做什么”，大致可以按五层来理解。

框架层：Router 与 Start

TanStack Router 是这套体系的路由基础。它把路由树、路径参数、搜索参数、loader、预加载和 pending 状态纳入类型系统。尤其是搜索参数，它不再只是一个字符串，而可以有明确的结构、解析和序列化规则。

这种设计很适合数据密集型应用：列表筛选、分页、排序和详情页状态都能映射到 URL，loader 又可以和查询缓存配合。路由因此不只是页面切换工具，而变成了应用数据流的一部分。

这种设计真的非常 nice，我们不用再去花时间精力找各种不同的解决方案。

TanStack Start 则在 Router 之上继续向全栈靠近。它提供服务端渲染、流式输出、服务端函数、服务端路由和面向不同运行时的构建结果。官方目前仍标记为 RC，这个状态很重要：它代表产品方向已经清楚，但基础设施仍处于快速打磨阶段。

数据与状态层：Query、DB、Store 与 AI

Query 是最成熟、最容易理解的一层：它负责远程数据的缓存、同步和更新。

DB 试图把客户端数据存储做得更具反应性，让接口数据可以在本地形成可查询、可订阅的关系。Store 更靠近一般客户端状态，但仍然延续轻量、类型友好的思路。AI 则把流式文本、工具调用、多模态和 agent 场景纳入同一套 TypeScript 接口。

官网当前将 DB 标为 beta、AI 标为 beta、Store 标为 alpha。把这些状态公开标出，既是风险提示，也是一种产品管理方式：用户可以清楚知道 Query、Router 这样的成熟工具，与新工具之间并不处在同一个稳定等级。

UI 与体验层：Table、Form 与 Hotkeys

TanStack Table 的定位很典型：它是 headless 的表格引擎，不替你决定 HTML、CSS 和组件外观。排序、筛选、分组、分页、行选择等能力由它提供，最终如何渲染由应用自己决定。

这条路线和“开箱即用”的表格组件不同。它牺牲了一部分上手速度，换来设计自由、组件库兼容性和更细的性能控制。Form 与 Hotkeys 也延续同样思路：提供状态和行为模型，不强迫应用接受一套视觉语言。

性能层：Virtual 与 Pacer

Virtual 负责大列表、大表格的窗口化渲染，让应用只渲染视口附近的数据。它和 Table 的组合很自然：Table 管理数据模型，Virtual 管理可见范围。

Pacer 更像是性能调度工具，用来处理节流、防抖、批处理和高频更新。它们共同说明 TanStack 的关注点正在从“有没有功能”转向“功能在复杂数据量和高频交互下是否还能保持可控”。

工具层：Devtools、Config、CLI 与 Intent

Devtools 负责观察查询、路由和缓存；Config、CLI 和 Intent 则在把工程配置、项目初始化与 AI agent 的工作方式纳入产品范围。尤其是 Intent 这类工具，反映出维护者开始考虑一个新问题：未来不只有人会阅读文档和修改代码，agent 也需要可靠地发现、安装和使用这些能力。

上篇先写到这里

从 React Query 到产品矩阵，TanStack 的第一步是把服务器状态、路由、全栈边界和数据视图逐渐放进一套可组合的技术栈。下篇将继续从竞品和公开 Issue 出发，看看这些选择在真实工程里意味着什么。

在数字产品中，体验往往由许多小的反馈共同组成。一个清楚的界面、一次顺手的操作，都会影响用户对产品的判断。

本期主要内容：

• StyleKit —— 把网页风格、组件样式和提示词整理成可直接参考的资料库
• Cuelume —— 给按钮、链接和操作结果加上轻量的交互声音
• Its Hover —— 让图标随交互动作产生有目的的动画
• Mole —— 在终端清理、卸载、分析和维护 Mac
• FlowCV —— 用模板快速制作简历并导出 PDF
• MessAuto —— 自动提取 Mac 上的短信和邮件验证码
• react-hot-toast —— 轻量、可定制的 React 通知组件
• Atuin —— 同步、搜索并备份终端历史
• Flash 保存计划 —— 多年前玩过的《狂扁小朋友》重新出现在浏览器里
• BLEUnlock —— 用 iPhone、Apple Watch 或其他蓝牙设备自动锁定和解锁 Mac
• storage-book —— 从存储介质到文件系统，边学边实现 KnotFS
• Deep Agents 实战 —— 从零学习构建生产级智能体
• Wenyi —— 将长篇作品翻译成中文并保留书籍结构
• Codia —— 把代码转换成适合分享和文档使用的图片

StyleKit

StyleKit 收录了 135 种视觉和布局风格，每种风格都配了颜色、字体、组件样式和提示词。还有页面示例、动画、页面模板，可以先看效果，再决定页面往哪个方向走。

这类资料可以把抽象的风格描述转换成可查看的视觉参考。做页面时，与其只写“帮我做得高级一点”，不如同时提供颜色、字体、组件和示例，AI 更容易对齐目标。需要制作页面时，可以先浏览 stylekit.top。

Cuelume

Cuelume 准备了 14 种交互声音，声音由浏览器即时合成，不需要准备音频文件，也不增加运行时依赖。

iPhone 里有好多种铃声：来电、短信、日历提醒、充电提示，每一种声音都在告诉你“发生了一件事”。如果网站也需要给按钮按下、操作完成、加载结束这些动作增加声音反馈，Cuelume 提供了一套比较轻的做法。

悬停、按下、松开、切换、成功、报错、加载完成，都可以用 data-cuelume-* 属性标记，再调用一次 bind()。示例页里还可以直接试听这些声音：cuelume-site.pages.dev。

这个项目把“什么动作配什么声音”整理成了可以直接尝试的示例。对于需要给界面增加声音反馈的场景，可以先从这些预设开始，再根据产品的操作节奏进行调整。仓库里也提供了 npm install cuelume 的安装方式。

Its Hover

Its Hover 是一个基于 React 和 Motion 的动画图标库，提供 186+ 个图标，覆盖界面基础操作、社交、技术品牌和状态提示等场景。

图标支持复制源码后继续调整动画、描边宽度和颜色，也可以通过 shadcn 命令直接加入项目。悬停、点击、加载和状态变化都能配合动画，让图标承担一部分操作反馈。完整图标可以在 itshover.com/icons 中查看。

Mole

Mole 是一个面向 macOS 的终端维护工具，提供清理缓存、卸载应用、分析磁盘、清理项目构建产物和查看系统状态等命令。

常用入口包括 mo clean、mo uninstall、mo analyze 和 mo status，清理和卸载操作都提供 --dry-run 预览方式。它适合需要在终端集中处理 Mac 垃圾文件、应用残留和开发产物的场景，但涉及删除的命令仍应先检查预览结果。

FlowCV

FlowCV 是一个在线简历制作工具，提供 50 多个模板，可以导入已有简历内容、调整版式和设计，并导出无水印 PDF。

免费方案支持创建和下载一份简历，内容可以持续编辑，模板和版式也能继续调整。需要快速整理求职简历、制作不同版本，或者把已有 PDF、DOCX 内容重新排版时，可以用它先完成基础版本。

MessAuto

MessAuto 是一个 macOS 应用，用 Rust 编写，可以自动提取短信和邮件中的验证码，并把验证码粘贴到当前输入框。

它支持监听 macOS 的信息和邮件应用，提供自动粘贴、自动回车、不占用剪贴板和浮动提示等选项。使用前需要授予“完全磁盘访问权限”和“辅助功能”权限，并保持信息或邮件应用在后台运行。

react-hot-toast

react-hot-toast 是一个用于 React 的通知组件，支持自定义样式、Promise 状态通知、无障碍访问和无头式钩子，包含样式的体积小于 5KB。

安装后加入 Toaster，就可以在组件中调用 toast() 显示提示。它适合处理保存成功、请求失败、加载中等短暂反馈，不需要为每一种提示状态单独搭建一套弹窗结构。

Atuin

Atuin 用于同步、搜索和备份终端历史，支持端到端加密，也可以自托管同步服务。它支持 macOS、Linux 和 Windows，以及 bash、zsh、fish 等常见 Shell。

除了按命令内容搜索，还可以按目录、退出码、执行耗时和主机名筛选历史记录。安装后运行 atuin setup 即可完成基础配置，适合经常在多台设备之间切换、又需要找回旧命令的开发环境。

Flash 保存计划

Flash 保存计划 收集了可以直接在浏览器里运行的 Flash 时代网页内容。这里重新发现了多年前玩过的《狂扁小朋友》，熟悉的画面和操作方式一下子回来了。

这类小游戏以前通常要安装 Flash 插件才能打开，现在通过网页就能重新体验。对小时候玩过的人来说，它更像一个可以直接打开的旧收藏夹；对没接触过的人，也能看到早期网页游戏那种简单直接的交互方式。

BLEUnlock

BLEUnlock 是一个 Mac 菜单栏工具，可以根据 iPhone、Apple Watch 或其他蓝牙低功耗设备的距离，自动锁定或解锁 Mac。

它不需要安装 iPhone 配套应用，选定附近设备后即可工作，也支持在锁定和解锁时执行脚本、唤醒屏幕和暂停媒体播放。首次配置需要授予蓝牙、辅助功能和钥匙串等权限，自动解锁类工具建议先确认使用场景和权限范围。

storage-book

storage-book 是一本从存储介质、Flash 物理到文件系统理论的开源技术书，也带着读者用约 840 行 C 代码实现教学级文件系统 KnotFS。

全书从磨损、掉电和噪声这些底层问题讲起，再进入 FAT、日志结构、磨损均衡和 LittleFS 源码。适合想把“文件保存”这件事往硬件和实现层继续追下去的人。

Deep Agents 实战

Deep Agents 实战 是一套围绕 LangChain、LangGraph 和 Deep Agents 的开源课程，内容从第一个智能体开始，逐步讲到虚拟文件系统、任务规划、子智能体、技能、长期记忆和沙箱执行。

它更像一套按工程问题组织的学习路线，而不是只展示一个能运行的对话示例。想了解智能体如何处理复杂任务、管理上下文和控制执行风险，可以从课程目录开始看。

Wenyi

Wenyi 是一个面向长篇作品的翻译工具，支持 EPUB、FB2、TXT、Markdown、HTML 和 PDF，并可以生成中文或双语版本。

它会先分析整本书，再结合滚动上下文、术语表、润色和复核流程处理章节，适合需要保持人名、术语和叙事一致性的长篇翻译场景。项目目前仍在早期阶段，实际使用前需要准备模型服务和对应的密钥。

Codia

Codia 可以把代码转换成适合文档、博客、社交媒体和自动化流程使用的高清图片，既提供页面操作，也提供方便 Agent 调用的 API。

如果需要把一段代码整理成更容易阅读和分享的视觉内容，可以直接选择语言、样式和代码片段后生成图片，省去反复调整截图和排版的过程。

最后

持续关注前沿工具与优秀实践，是提升专业能力的重要途径。感谢您陪伴本期周刊，我们下期再见。

前言

这一年来，越来越多的开发者开始接触甚至是大量使用 Agent AI。无论是写代码的助手、自动化运维工具、企业知识库问答，还是带有工具调用的智能体应用，很多项目都不再只是“调用一个大模型接口，然后输出一段文本”这么简单，而是开始让模型去执行命令、读写宿主环境的文件、访问数据库、调用浏览器和操作云端资源等等。

一旦走到这一步，很多开发者很自然会接触到这个东西：第三方中转服务。

它通常也叫做 API 中转、代理路由、统一网关、转发服务等。

说实话，我一开始找中转的原因也很简单：就当世最强几个模型来说，官方真的贵，而且容易遇到额度、速度或可用性问题。对普通开发者来说，中转看起来像是一个很自然的选择。

国内中转，可以做到官方服务价格的一半甚至更低。一开始，我的关注点只有两个：

• 价格是否合适
• 服务是否稳定

但当我把它放进 Agent AI 的上下文，问题就不止是成本和可用性了，还会多出第三个更重要的问题：安全性如何？

就是一个经典的不可能三角，谁也没有把握能说自己能找到最完美的答案。

最近一篇论文《Your Agent Is Mine: Measuring Malicious Intermediary Attacks on the LLM Supply Chain》专门研究了这一点。

它的核心观点非常值得普通开发者了解：当 AI Agent 通过第三方中转服务调用模型时，这个中转节点并不只是“网络转发器”，而是一个拥有真实安全影响力的信任边界。

在某些情况下，它甚至可以决定你的 Agent 最终执行什么命令。

这听起来确实有点吓人，但我们也不必因此过度悲观。

更准确地说，正确理解这个问题，反而能够帮助我们更加成熟地使用中转服务，而不是因为“担心风险”就彻底放弃它。

这篇文章就想用尽量直白的方式，和普通程序员聊聊：

• 第三方中转服务到底是什么
• 为什么 Agent 场景下风险会明显放大
• 中国大陆开发者为什么更容易接触这类服务
• 真正需要担心的风险是什么，不需要过度担心的又是什么
• 如果必须使用中转服务，怎样把风险降到更合理的范围

什么是第三方中转服务？

正常情况下，你的程序直接请求模型厂商，比如 OpenAI、Anthropic、Google 等。

但在现实开发中，很多人并不是这么接的，而是把请求先发给一个“中间平台”，由它再转发给真正的模型提供方。这就是中转服务。

它之所以流行，主要有几个很现实的原因：

第一，统一接口。

不同模型厂商的 API 格式不一样。中转服务经常会把它们包装成统一格式，开发者只要接一个接口，就能切换多个模型。

第二，成本和可得性。

对于国内开发者来说，这一点尤其现实。有的人是为了便于访问，有的人是为了聚合多个渠道，有的人是为了用更低门槛测试不同模型，有的人只是想先跑通项目原型。

第三，功能增强。

有些中转服务会提供模型 fallback、负载均衡、缓存、统一计费、日志、密钥管理、额度分发等能力。这些对团队开发确实很方便，用量和成本可以衡量出来。

所以，使用中转服务本身不是“错误做法”，它有非常真实的工程价值。

问题在于：很多人把它理解成了“只是帮我转发一下请求”。问题在于，中转服务并不只是“帮你转发一下请求”这么简单。

在 Agent 场景里，中转服务为什么更敏感？

如果你只是做一个普通聊天机器人，中转服务的风险虽然存在，但还相对容易理解： 它能看到你的 prompt、用户输入和模型输出。

但 Agent 不一样。

Agent 的核心是“根据回答进一步执行动作”。 这些动作可能包括：

• 执行 shell 命令
• 安装依赖
• 读取和修改代码文件
• 调用数据库
• 操作浏览器
• 使用云平台密钥进行部署或运维等等

Agent 可以做的事情太多了！

在这个场景下，调用大模型返回的内容就不再只是文本，而可能是一个工具调用指令，里面包含要执行的命令、参数、路径、目标地址等。

论文指出，当前生态里广泛存在一个问题：没有成熟的端到端机制，能证明 Agent 最后看到并执行的 tool call，一定就是上游模型原始生成的那个 tool call。

这就意味着如果中转服务愿意，它不仅可以看到你的请求和响应，还可能改写它们。

比如，上游模型原本想让 Agent 执行一个正常命令，但中转层可以把这个命令偷偷换掉，然后再返回给客户端。只要 JSON 格式还合法，Agent 可能根本察觉不到。论文把这种行为归纳为响应侧载荷注入（AC-1）。

个人观点：他们可以这么做。一旦有足够利益的驱使，他们非常非常有可能会这么做。

论文告诉了我们什么？

这篇论文《Your Agent Is Mine: Measuring Malicious Intermediary Attacks on the LLM Supply Chain》把风险拆得很清楚：

• 改写返回结果，让 Agent 执行错误动作
• 不改内容，只是偷偷收集敏感信息

第一种是最直观的一类风险。论文称之为 Payload Injection。也就是说，中转服务可以篡改模型返回的工具调用参数，比如把下载地址换成攻击者控制的脚本、把正常命令改成 恶意命令。

如果你的 Agent 拿着高权限运行，而你又没有做足够的审批和隔离，那么这种篡改带来的后果会非常严重。

第二种风险甚至更隐蔽，论文把它称为 Passive Secret Exfiltration。也就是中转服务什么都不改，只是静静地扫描流经它的明文数据，把 API Key、云凭证、某种私钥、数据库地址、内部 Token 等敏感信息记录下来。

我的敏感信息就是这样泄露的 😭

这类风险最容易被普通开发者低估，因为你的系统表面上“运行完全正常”，日志也不一定有异常，但秘密已经被别人看见了。

国内开发者真的非常需要理解这个问题

这个问题在全世界都存在，但国内开发者可能更容易遇到。由于某种限制，我不方便讨论这方面的原因，相信在大家心中都有自己的答案。

就像那个经典笑话一样，某个国外的开发者认为咱们中国开发者是最注重隐私的balabala 🤣

这就导致一个现象：很多开发者并不是先学会“如何安全地信任中间层”，而是先学会“怎么把接口跑通”。

从项目推进角度看，这很正常。谁做原型都想先把东西做出来。

但如果一个项目后面逐渐接入了真实代码仓库、企业数据库、生产环境云资源、内部文档、运维工具，这时候再把中转服务只当“便宜点的 API 渠道”，就太危险了。

我们要知道的是：我们把模型请求发给中转，也就把 prompt、上下文、工具定义、命令内容、文件路径、甚至密钥暴露给了它。

在 Agent 场景里，你还可能把“实际执行语义”交到了它手上。

理解这一点，并不是为了让大家拒绝一切中转，而是为了避免一种非常常见的错误心态：

“这是模型层的事，不是安全层的事。”

实际上，它已经是安全层的事了。

研究团队对 28 个付费的 API 中转站 (来源于淘宝、闲鱼、Shopify 等店铺) 和 400 个免费中转站 (来自公开社区) 进行全面评测，结果触目惊心。

• 1 个付费中转站 + 8 个免费中转站会在响应中主动注入恶意代码
• 上面这 9 个中转站中有 2 个还部署了自适应规避触发器
• 17 个中转站触碰了研究团队故意部署的 AWS 诱饵凭证
• 1 个中转站直接窃取了研究团队放在蜜罐中的资金

总结一下，论文直接覆盖的风险：

• 篡改工具调用，诱导 Agent 执行恶意命令
• 被动收集 API Key、云凭证、私钥、内部 Token 等敏感信息

在现实中，中转服务商还干过这种事（不是扯淡，互联网有记忆）：

• 模型调包与降级
• 预充值积累了资金，服务商连夜跑路
• 上游账号违规导致整体服务中断，不然你以为那么多账号哪来的？GitHub 现在都还有批量注册账号的项目，作者还是国人...

普通开发者应该怎么做？

这就是现实世界，危险无处不在。

但是如果害怕危险而畏首畏尾，那就本末倒置了，我们也别追求“绝对安全”了，风险和权限匹配就行了。

如果后果只是改坏一个测试项目、影响本地临时环境，那容忍度可以高一些。

如果后果是泄露公司代码、误删云资源、读到生产数据库、把内部文档发出去，那就应该尽量避免走不可验证的第三方中转。

永远不要把“主密钥”直接交给 Agent，无论是否使用中转，这都是基本原则。

Agent 应该拿到的是最小权限、最短时效、最可审计的凭证，而不是“能干所有事”的万能 Key。

即使真的泄露了，也要把损失限制在一个很小范围内。

为什么非要找中转？如何寻找“靠谱”中转服务商？

既然中转有这么多问题，为什么大家还要找中转？

还是那句话，中转服务解决的是真问题：

• 它让接入多个模型变简单
• 中转能做容灾和 fallback
• 它有时候确实更便宜，更容易获得，甚至它降低了 Agent 原型开发的门槛

其次，我不会在这里推荐任何中转服务商，但是根据我用过的若干服务商的经历，我想给大家一些关于如何筛选中转服务商的建议。

• 远离“超低价、全模型支持、无限量”，不要贪小便宜，中转服务不是做慈善，羊毛出在羊身上
• 没有隐私政策、安全说明、公司主体和联系方式的中转，默认按高风险看。只给一个 API 地址和充值入口、却不说明上游来源的服务，尽量别碰。
• 舍得花钱做营销（开源热门项目赞助、著名论坛硬广）、信息公开透明、服务团队响应公开快速最佳（服务商入群又不收费，进去看看又何妨）
• 能不能退款、有没有试用或者短期套餐很重要

最后

现在这个时代，公司如果给员工提供 AI 服务或者官方的订阅真的是太好了，省下一笔钱不说，你自己用个第三方的服务，出了问题还得担责。

第三方中转服务这件事，值得你从今天开始认真看待。一旦你把 Agent 接进真实工具链，它就会变成安全问题、权限问题和责任问题。

真正值得警惕的，是你根本不知道自己在信任谁。

感谢大家看到这里，如果你喜欢我分享的内容，欢迎给我三连支持，你的支持是我更新下去的动力！

下次见，Bye 👋🏻

从 Netflix 的架构演化，看 JavaScript 的新定义

前言：谁定义了「核心系统」？

在传统后端世界，「核心系统」意味着： 数据库、支付、事务、锁、一致性。

这些模块稳定、严谨、克制——它们是系统的「引擎室」。

但到了 2025 年，用户体验已取代数据表成为真正的竞争力。 对用户来说，决定留存的不是数据库锁，而是响应延迟、首屏速度、播放流畅度。

于是，新的问题出现了：

“你说 BFF 不是核心业务层，那谁定义的核心？ 是数据库锁，还是用户体验？”

如果“核心”指的是决定体验、延迟与系统弹性的部分， 那么在 Netflix、Shopify、Vercel、Cloudflare 等公司， 真正的系统核心，已经不是 Java 或 Go。 而是 —— Node.js。

一、旧范式：后端的克制哲学

后端工程师的信条一直是“克制”：

• 静态类型，避免歧义；
• 错误显式，拒绝魔法；
• 工具统一，降低分歧；
• 简洁可测，优先维护。

这正是 Go、Rust、Java 等语言的哲学。 它们带来了稳定性，但也带来了“重、慢、僵”的代价。

JavaScript 曾被视作「玩具语言」， 但在十年间，它从浏览器脚本成长为全栈基石：

• 浏览器端：React / Vue / Svelte
• 服务端：Node.js / Hono / Nest.js
• 边缘端：Cloudflare Workers / Deno / Vercel Edge
• 数据层：Prisma / Drizzle / Supabase

Node.js 的意义，不只是“让前端能写后端”， 而是让整个系统生态语言统一、协作无缝。

二、现实案例：Netflix 的 Node.js 革命

架构图（2024–2025）

[终端用户]
   ↓
[Edge CDN]
   ↓
[Node.js BFF / API Platform]
   ↓
[Java / Go 微服务层]
   ↓
[Cassandra / MySQL / Kafka]

Netflix 的 Node.js 层不是“辅助接口”， 而是整个系统的 流量咽喉：

• 唯一触达用户的后端；
• 决定 90% 延迟的关键层；
• 承担个性化、聚合、SSR 等重型逻辑。

真实指标（2025）

这些数据来自 Netflix 工程博客与公开访谈（2023–2025）。

这不是“轻量接口层”。 这是全球最大规模的 Node.js 集群之一。

“Node.js 扛下 100% 用户流量， 决定 90% 延迟与体验， 不是前戏，而是主角。” ——Rocky Bhatia, Netflix Platform Team Lead

三、Node.js 的“核心定义”重写

在 Netflix，「核心」的定义被颠覆了： 核心，不再是“写入数据库”，而是“谁决定响应体验”。

四、Node 的扩张路线：从 BFF 到 Platform

Netflix 的转变可以用一句话概括： “从接口层到平台层。”

“We are migrating Java services to Node.js for better developer productivity and reduced latency.” ——Netflix Tech Blog, Node.js at Netflix: The Next Chapter (2023)

到了 2025 年，Node.js 已占 Netflix 微服务总量的 20%+：

• 平均延迟 ↓20%
• 开发速度 ×3
• 协作效率 +50%
• 统一语言栈 → 消除了“后端 vs 前端”壁垒

Node 不再只是“BFF”， 而是 Netflix 的 API Platform 层，负责：

• 分布式数据聚合
• 智能缓存与状态预热
• GraphQL Federation 查询优化
• 边缘渲染与实时个性化

“从 Java 迁 Node，不是‘some’， 而是战略性语言统一。” ——Netflix Architecture Council, 2025

五、性能：Node 的异步效率

Netflix 内部实测（2024）：

Node.js 以更高内存换来了更高吞吐：

• 异步 I/O 极致复用；
• 连接池缓存热数据；
• 无阻塞事件循环应对峰值流量；
• 实时状态预热减少重试 40%。

Node 的模型是“动态压舱石”—— 流量越高，伸缩越快。

六、Node 的工业级成熟度

Node.js 生态在 2025 年已全面工业化。

Node 不仅稳定，还具备「可观测 + 可自治 + 可自愈」三要素。

Node 不再是“脚本”， 它是现代互联网的分布式平台语言。

七、Monorepo：Node 的协作革命

Netflix、Shopify、Vercel 均采用 Monorepo 模型：

/apps
  /web
  /tv
  /mobile
  /bff-node-service

• TypeScript 类型共享
• GraphQL Codegen 自动生成接口定义
• ESLint + Prettier 一致风格
• GitHub Actions 自动化测试

50 人团队、百万行代码、零冲突。 Node 不是“灵活”失控的语言，而是高度约束的工程体系。

纪律不是 Go 的特权， 它可以是 JS 的自觉。

八、Netflix 架构的“平民版”

Netflix 的 DevOps 成本，如今任何中小团队都能平替。

Shopify 用 Node Monorepo 承载 1 亿商家，零 Go。

“复刻 Netflix 架构” 已不再是企业梦， 而是云端标准模板。

九、Node 的胜利，是体验的胜利

Go 的设计哲学是「克制」； Node 的哲学是「统一」。

Go 追求确定性； Node 追求体验流畅性。

Netflix 的语言演进不是「替代」， 而是「统一」：

“让所有面向用户体验的系统，用同一种语言思考。” ——Netflix Developer Experience Team

Node.js 成为“用户层 + 数据层”之间的中枢神经系统。

十、为什么 Netflix 不“转向 Go”？

Netflix 没换 Go，因为 Node 已经跑得够稳、够快、够清晰。 Go 的“确定性”没有实际收益， Node 的“统一协作”反而创造价值。

Netflix 投资自家 Node FaaS 平台， 说明 Node 已从“语言”升级为战略层资产。

十一、Node.js 是现代后端的体验引擎

Node.js 是新时代的“体验层后端”。 它不是替代 Go，而是重塑“核心”的定义。

最后：语言的尽头，是协作与体验

Go 的克制让系统稳如磐石； Node 的统一让协作顺畅如呼吸。

未来的后端，不再以「静态 vs 动态」划界， 而是以「封闭 vs 协作」分胜负。

Go 是企业的地基， Node 是产品的呼吸。

在体验为王的时代， 真正的核心， 不是谁拿着数据库锁， 而是谁点亮了屏幕的那一毫秒。

最终总结

• Netflix 没有转向 Go，因为 Node.js 已是它的「体验心脏」。
• Node 从 BFF 进化为 Platform，从接口层变为体验核心。
• 2025 年的 JS 生态，让普通团队也能复刻 Netflix 的架构思想。
• Node 代表新的后端范式：统一语言、异步模型、体验为核。

Node.js 不只是前端的延伸， 它是现代互联网的全栈中枢。

它不是“轻量”， 它是未来。

推荐引用来源（部分）

• Netflix Tech Blog – Node.js at Netflix: The Next Chapter, 2023
• Rocky Bhatia Substack – The 100B Request BFF Layer, 2024
• DesignGurus – Netflix Node.js Architecture (2025)
• InfoQ – GraphQL Federation in Netflix Node Layer, 2025
• TheNewStack – Netflix FaaS Node Platform Evolution, 2025

写在最后：

在后端世界的克制与前端世界的热情之间， Node.js 找到了连接的平衡点。

它不是边缘语言， 它是新时代系统的——中枢神经。

大家好，今天想和大家讨论和分享一下我对 web 项目里 NODE_ENV 环境变量的看法。

前言

在很多 web 项目里，环境变量的设计往往是一个“看起来简单，但实际非常容易踩坑”的问题。

最典型的就是：

NODE_ENV 到底应该怎么用？ dev / test / staging / prod 要不要塞进 NODE_ENV？

这几年来我经历过各种大小草台班子，接手过各种 web 项目，看到很多团队图省事，会把所有环境都塞进 NODE_ENV，比如：

NODE_ENV=dev 
NODE_ENV=test 
NODE_ENV=uat
NODE_ENV=staging
NODE_ENV=prod

这种方式前期看似乎没问题，但随着项目变复杂，需求、环境变多，参与人数变多等等，这种设计基本都会逐渐变成隐患。

今天分享这篇文章，主要想和大家分享一下，我们得搞清楚一下几点：

• NODE_ENV 的本质是什么？
• 为什么不能把它当环境枚举
• 运行时变量应该如何设计
• 推荐的实践方案

NODE_ENV 的本质：运行模式

NODE_ENV 是 运行模式。

很多测试框架会强制设 NODE_ENV=test

当我们在项目里需要判定当前逻辑所处的运行模式是什么的时候，记住：在 Web 开发中， NODE_ENV 其实有着非常明确的约定：

很多框架和库都会根据 NODE_ENV 自动设定一些行为，比如：

• 是否输出详细错误信息
• 是否开启调试日志
• 是否启用性能优化
• 是否使用缓存
• 是否压缩资源

如果你把 NODE_ENV 改成：

NODE_ENV=uat
NODE_ENV=staging

这些库很可能识别不了，从而导致行为异常。

概念误区： 把 NODE_ENV 当环境名

我曾经把 NODE_ENV 当成”当前代码运行在哪一个环节“的判定依据：

if (process.env.NODE_ENV === 'dev') {} 
if (process.env.NODE_ENV === 'uat') {} 
if (process.env.NODE_ENV === 'staging') {}

这里其实混淆了两个基本概念：

• 运行模式 - mode
  • 是否开启调试：development 开启，production 关闭
  • 是否压缩日志：development 关闭，production 开启
• 部署环境 - environment
  • dev 开发环境
  • test 测试环境
  • prod 生产环境

或许我们不应该用同一个变量来表示这两种概念。

对吧？运行模式的关注点在于代码如何运行，我们根据这一点来控制是否调试、是否输出细节，启用 source map，运行模式会影响打包结果，并且应该进入构建产物内部，我不在乎这份代码构建后在什么环境下运行。

然而部署环境就不一样了，它的核心关注点是：代码运行在哪里？

举个例子，假设代码运行在 test 环境下，我们正在对代码进行测试，难道这时候你想要让类似 Sentry 这样的第三方服务接入进来吗？

当然不需要！就算是免费的服务，也不需要在测试的时候接进来啊，白嫖也不行！

我们需要用一个变量来标识部署的环境，也可以说是运行的环境。

但现实是很多团队、项目会一把梭 NODE_ENV，某种意义上来说，这个变量传播最早也最广，大家习惯了用它控制一切。

并且，一个变量就能决定“开发时友好，生产时高效”，确实方便。

但我们不能忽略这样做的代价：

• 语义不清晰：NODE_ENV=production 时，到底是“打包成生产模式”还是“当前部署在生产环境”？经常说不清。
• 无法灵活组合：我想在 test 环境也用 production mode（为了测性能、测构建产物），或者在 prod 环境临时开启 development mode 调试问题，就很尴尬。
• 配置爆炸：很多人最后搞出 development, test, staging, production 四种模式，却又在里面嵌套各种 feature flags，配置越来越乱。

推荐做法：NODE_ENV + APP_ENV

在前端项目中，NODE_ENV 主要影响构建结果（Vite/Webpack）；在后端（如 Node.js/NestJS/Express）中，更建议用 APP_ENV 控制业务配置。

NODE_ENV：只保留给构建工具使用（vite/rollup 等），严格只有 development / production 两个值。

APP_ENV 或 DEPLOY_ENV：真正代表部署环境（dev/test/staging/prod）。

举个例子：一个电商系统的 Staging 环境

Staging 环境的定位：

• 目的是在上线前做最接近真实生产的完整测试（包括性能、功能、集成）。
• 通常由 QA、产品、运维一起验证，模拟真实用户流量。
• 核心需求：行为要和生产环境几乎一致，但数据和外部服务是隔离的。

如果不分开（只用一个变量，比如 NODE_ENV 或 ENV），可能有人会这样写：

# 很多人会这么写
ENV=staging
# 或者
NODE_ENV=staging

然后代码里这样判断：

if (process.env.NODE_ENV === 'production') {
  // 生产行为：压缩、关闭调试、无彩色日志等
} else {
  // 开发行为：详细日志
  // source map、React DevTools 等
}

在 staging 环境下会出现以下问题：

想用 production mode 的优化，但环境变量是 staging。

结果是用了 development 模式：代码没压缩、日志超级详细、source map 没去掉、性能比生产差很多，无法准确验证性能和稳 定性。

想用 development mode 方便调试，但又怕污染生产行为。

如果强行设 NODE_ENV=development，那整个 staging 就失去了“类生产”的意义，测出来的结果不可信。

配置冲突：数据库要用 staging 专属的库（不能连 prod DB） 支付、短信、推送等第三方服务要用测试账号，但日志、监控、告警又希望和生产保持一致（格式、级别、压缩方式）

最终结果：要么 staging 测不准，要么调试很便秘，花费的时间大大增加，然后？导致加班 ？🤣

现在就以这个为例，我们试试看拆开成两个变量：

# 运行模式（决定代码如何运行、打包结果）
NODE_ENV=production        
# 或 APP_MODE=production

# 部署环境（决定连哪个数据库、用什么密钥、开哪些功能）   
# dev | test | staging | prod
APP_ENV=staging       

其他场景下，NODE_ENV 基本都设置为 production！部署环境则根据 test、staging、prod 来切换逻辑。

在这个 Staging 环境下，运行模式是 production，构建后：

• 代码是压缩的、tree-shaking 后的
• 肯定没有 source map
• 日志是结构化的，压缩的，不至于打印多余的彩色日志，详细堆栈也不会暴露
• 框架的开发警告全部关闭
• 性能和生产环境一致

同时，部署环境是 staging：

• 根据部署环境连接 staging 数据库（当然也可以在 CI 的时候专门注入数据库链接）
• 测试支付渠道走的是沙箱
• 独立的 staging 域名、监控 Tag、开放的功能

代码示例：

const mode = process.env.NODE_ENV;        // production
const env  = process.env.APP_ENV;         // staging

// 构建/运行时行为
const isProdMode = mode === 'production';

// 业务和基础设施配置
const config = {
  db: {
    host: env === 'prod' ? 'prod-db' : `${env}-db`,
  },
  logging: {
    level: isProdMode ? 'info' : 'debug',
    pretty: !isProdMode,
  },
  features: featureFlags[env],   // staging 可以有独立的 feature flags
};

甚至配置文件也可以按 APP_ENV 拆分：

• .env.local
• .env.dev
• .env.test
• .env.staging
• .env.prod

这样一来我们就可以去做一次性构建，多环境部署。

在 CI/CD 的过程中，只需要构建一次代码，再部署到多个环境即可。多环境下多次重复构建就显得有点浪费时间了。

写进 README 的规范

以下几点，我将之写入了自己所有项目的 README 中

• NODE_ENV 只允许：development / test / production
• APP_ENV 用于区分部署环境：local / dev / test / staging / prod
• 除本地开发和自动化测试外，所有服务运行在 NODE_ENV=production
• 禁止使用 NODE_ENV 判断 dev/test/staging/prod
• 所有环境差异统一通过 APP_ENV + 配置文件管理

如果你正在做一个中大型后端系统，这一条设计，值得你在一开始就定对。否则后面重构成本会非常高。

如果你已经在用 NODE_ENV=dev/staging/prod，也可以逐步引入 APP_ENV，把职责拆清楚，就能平滑过渡。

最后

最近 AI 的发展实在是太快了，很多人已经完全不再编写代码，Vibe coding 堪比许愿，在 Agent 帮助下，连自己review 都省了。

但是，我还是觉得 AI 只是拓展开发者能力的工具，至少目前还是！我们可以借助 AI 来做很多原本自身做不到的事情，或者需要花很多时间精力才能做到的事情。但是在开发这件事情上，一切的根基还是我们自己。

感谢大家看到这里，如果你喜欢我分享的内容，欢迎给我三连支持，你的支持是我更新下去的动力！

下次见，Bye 👋🏻

我们可能遇到这样的情况：

• 某个按钮样式异常，但项目里有七八个同名 class
• 文案写错了，搜索关键词却找不到它实际渲染的位置
• React/Vue 中的组件结构层级复杂，想定位某个节点的来源需要跳几个文件
• 别人写的老项目，目录结构复杂、组件命名不统一

这些情景并不少见，甚至有时比写业务本身更让人头痛。

code-inspector-plugin 正是在这种背景下，提供了一个非常直接的解决方式：

从页面点击元素，直接跳回编辑器中对应的源码行。

下面通过一个真实例子来说明它能带来什么样的改变。

一个常见的场景：定位样式问题

假设你正在维护一个后台管理系统。设计师反馈：

“首页统计卡片 hover 的动效好像不对，你看一下。”

你打开页面检查 DOM，发现这个卡片由多个组件嵌套而成：

Dashboard
  └── OverviewCardList
        └── OverviewCard
              └── CardPanel

但 class 名和组件名都较通用，比如：card-wrapper、panel、container。 你试图在项目中搜索，但无法精准定位到底是哪一个组件渲染了你看到的这个卡片。

在传统方法里，你可能会：

• 根据 class 搜索
• 翻几个文件
• 找不到就继续往上排查
• 几分钟过去了，问题的根本位置还没找到

没有什么比我们的时间更加珍贵的了！

使用 code-inspector-plugin 后的体验

你按住 Shift，在浏览器里点击这张卡片。

macOS 和 windows 快捷键有所不同

VSCode 立即打开：

src/components/OverviewCard.vue:52

光标正好停在渲染这个卡片的那一行。

你只需要补上一段样式：

.overview-card:hover {
  transform: translateY(-4px);
}

刷新 → 完成。

整个流程非常直接，没有搜索，没有猜测，也无需在组件树里“盲走”。

实现机制很简单，但非常有效

在开发模式下，插件会：

1. 为每个 DOM 对应的源代码位置生成一个标识

2. 拦截你在页面中的点击事件

3. 向本地服务发送“打开文件并跳转行号”的指令

4. 编辑器执行类似：

   code --goto src/...:line
   

5. 即刻跳转到源码

生产环境构建时，所有注入信息会自动被移除，不会影响体积，也不会泄露源码路径。

快速上手（以 Vite 为例）

安装

pnpm add code-inspector-plugin -D

配置

import codeInspector from 'code-inspector-plugin/vite'

export default defineConfig({
  plugins: [
    codeInspector({
      bundler: 'vite',
      showSwitch: true,
    })
  ]
})

此插件为常见的编译工具都提供了对应的解决方案，如果你使用的不是 vite，也可以在官方文档页面轻松找到对应的配置。

启动 Dev Server 后：

• Shift + 点击任意页面元素 → 编辑器自动跳转
• 左下角会出现一个开关，用来临时启用/禁用

支持 Vue、React、Svelte、原生 HTML 等常见开发模式。

适用场景

• 大型项目中快速定位组件来源
• 新同事 onboarding，提高理解项目结构的速度
• 排查样式、文案、布局问题
• 老项目维护
• 组件库调试
• 后台系统或多层嵌套组件场景

特别是在你不确定“这个元素到底来自哪个组件”的时候，它的价值会非常明显。

结语

code-inspector-plugin 并不是一个复杂的工具，但它在最基础的开发行为上提供了非常高的效率提升： 从页面回到源码，让定位问题变得确定且高效。

code-inspector 没有改变框架，也不试图重新定义什么。它只是让开发过程里最琐碎、最令人疲惫的那一部分变得轻松起来。

你可能会发现，它是那种“用过一次就离不开”的插件。

为什么不尝试一下呢？

🔗 参考与引用

1. code-inspector-plugin GitHub https://github.com/zh-lx/code-inspector-plugin
2. Vite 插件说明 https://github.com/zh-lx/code-inspector-plugin/tree/master/packages/vite
3. Webpack 插件说明 https://github.com/zh-lx/code-inspector-plugin/tree/master/packages/webpack

感谢大家看到这里，如果你喜欢我分享的内容，欢迎给我三连支持，你的支持是我更新下去的动力！ 下次见，Bye.

关键词：Node.js / Golang / TypeScript / 后端架构 / 全栈开发 / 性能瓶颈 / 语言哲学 / 团队协作 / 系统可维护性

引言：从热血到现实的转折

有一家创业公司，三年前凭借一支满怀热情的 JavaScript 全栈团队，仅用三个月就上线了他们的第一个 SaaS 产品。 前端用 React + Next.js，后端用 Node.js + Express + Prisma，全栈统一、开发高效、迭代迅速。

第一年，他们的产品飞速成长； 第二年，用户数突破百万； 第三年，系统频繁宕机、内存暴涨、日志爆炸、调试混乱—— 最终，他们重构了后端，转向 Golang。

这样的故事，在业界几乎每年都上演：

• Uber：从 Node 到 Go
• Airbnb：从 Node 到 Java
• 字节、美团：Node 留在 BFF 层，Go 承载核心后端
• Cloudflare：边缘层用 JS，主干流量全是 Go

问题不是 JS 不行，而是当系统足够复杂时，语言设计哲学的差异会被无限放大。

一、JavaScript 全栈的黄金时代

过去十年是 JavaScript 的全盛期。 从浏览器到服务器，从前端到云端，JS 几乎无处不在：

• 前端：React、Vue、Svelte、Next.js
• 后端：Node.js、Express、Nest.js、Hono.js
• ORM 层：Prisma、Drizzle ORM
• 构建工具：Vite、RSBuild、Webpack

“前后端统一语言” 带来了巨大的生产力革命：

1. 上下文一致：一个类型定义贯穿全栈；
2. 学习成本低：新成员快速上手；
3. 生态丰富：NPM 拥有世界上最多的包；
4. 快速原型：非常适合初创产品、内部系统、MVP。

这让 JS 成为快速创新的代名词。

二、当系统变“大”后，一切都变了

当一个系统从几千用户成长到上百万用户，从单人维护到百人协作， JS 的灵活反而成了负担。

1. 单线程模型的物理瓶颈

Node.js 的核心是事件循环（event loop）， 它通过异步 I/O 实现高并发，但依旧是单线程的。

优点：I/O 密集型场景（API 聚合、HTTP 转发）性能极高； 缺点：CPU 密集型计算（加密、日志压缩、图像处理）会堵死主线程。

即使 Node 提供了：

• worker_threads；
• cluster；
• 或者 Serverless 弹性扩展； 这都只是“绕过限制”，不是“根本解决”。

反观 Go：

• 多核天然并行；
• goroutine 轻量（百万级并发）；
• 调度由语言层托管。

JS 可以异步，但不是真正的并行。 Go 是原生并发，从根设计上解决性能扩展问题。

2. 内存管理的隐性代价

Node.js 使用 V8 引擎，默认内存上限约 1.5GB。 这在大型系统下意味着什么？

• GC 压力大，频繁触发时会造成抖动；
• 内存泄漏难排查（闭包残留、异步引用）；
• 跨模块调试复杂，线上分析痛苦；
• 工具链零散，profiling、heapdump、trace 都是外部插件。

而 Go 原生支持：

• pprof 性能分析；
• 自动 GC 优化；
• 编译期静态内存布局；
• 二进制部署时资源占用小。

JS 可以跑快，但长时间跑稳是一种奢侈。

3. 灵活性与混乱的临界点

JavaScript 的灵活是它的魅力，也是它的毒药。

• 你可以用回调、Promise、async/await 混着写；
• 你可以在运行时改对象结构；
• 你甚至可以写出行为不同的同名函数。

这在小团队里是创造力； 在大团队里是灾难。

TypeScript 改善了这一切——但并不彻底：

• 类型推导复杂，泛型嵌套难读；
• 类型定义随库变动频繁；
• 编译器耗时长；
• 高级类型体操成了新的陷阱。

Go 的哲学则相反： 限制是自由的前提。

三、后端是“克制的艺术”

Golang 的设计者 Rob Pike 曾说过一句话：

“A great language is one where you can’t write bad programs easily.” ——伟大的语言，是让人很难写出坏代码的语言。

Go 的简洁并非偶然，而是一种克制：

• 没有继承；
• 没有宏；
• 错误必须显式返回；
• 工具链标准统一；
• 自动格式化，代码风格一致；
• 语法几乎无歧义。

这让 Go 成为大型团队协作的天然选择。 在 Node 项目中，你可能要制定一百条 ESLint 规则； 而在 Go 项目中，只需要写：

go fmt ./...

然后一切都统一了。

Go 没有给你“更自由”的语法，而是给了你“更少犯错”的机会。

四、技术债与业务债的交织

即使是最强的 JS 团队，也无法长期避免“技术债 + 业务债”的双重爆炸。

1. 框架和依赖的短命循环

Node 生态的活跃，是 blessing 也是 curse。

• 五年前的 Express，如今已难维持；
• Nest.js、Fastify、Hono、Koa 等并行存在；
• 每个库的 TS 支持程度不同；
• NPM 依赖树深达数百层。

一次依赖更新，可能引发连锁崩溃。 Go 的 go mod 模块化机制，则天然避免了这种问题。

2. 可观测性与调试体验的差距

在生产环境中定位问题：

• Node.js 需要第三方库、独立 APM、日志链路拼接；
• Go 内置 net/http/pprof、runtime/trace、expvar；
• Java 有 JFR、JMX、VisualVM；
• Rust 借助 compile-time tracing。

当系统规模达到数十亿请求时，稳定性 = 成本控制。 此时语言的工程可观测性就决定了运营效率。

3. 团队扩张带来的复杂性放大

一个 5 人的 JS 团队可以写出优雅代码； 一个 50 人的 JS 团队，很容易写出一团糟。

因为 JS 的自由度太高、团队水平差异太大、规范约束难以 enforce。 Go 则几乎没有这种问题： 写出来的代码都一个样，逻辑清晰，学习成本低。

在协作密集的环境中，语言的约束性反而是一种安全性。

五、为什么“顶尖 JS 团队”仍然会转向 Go

即使拥有最强的 JS 技术能力，问题仍然会从外部逼近：

JS 团队可以凭经验压制问题，但语言特性本身的「物理规律」无法被消除。 随着规模增长，Go 的稳定性红利会逐渐超过 JS 的灵活性红利。

六、真实案例：从 JS 到 Go 的演进之路

Uber

最初的 API Gateway 基于 Node.js 构建， 后因性能瓶颈与异步调试困难，迁移到 Go， 结果 API 响应速度提升 50%，并发承载提升 3 倍。

Airbnb

早期使用 Node 作为服务层， 后改为 Java + Go 混合架构，解决高并发与内存泄漏问题。

Cloudflare

边缘计算层（Workers）仍用 JS， 但主干网络层全部使用 Go 实现，追求极致性能。

美团、字节跳动

Node.js 被限制在 BFF 层或工具层， Go 成为统一的后端主力语言。

结论很一致：

JS 很好用，但不适合扛大梁。

七、最合理的平衡：分层协作，而非替代

成熟的工程组织往往这样分层：

这种架构让各语言发挥所长，既保留 JS 的敏捷，又利用 Go 的稳定。

真正成熟的工程，不是语言之争，而是职责之分。

八、总结：从灵活到克制，从速度到稳定

• JS 全栈代表创新与效率；
• Go 体系代表稳定与可控；
• 选择语言，其实是选择团队的工程哲学。

JS 是创业期的加速器， Go 是企业期的压舱石。

当你追求的是“上线速度”，JS 全栈最强； 当你追求的是“稳定十年”，Go 才是答案。

尾声：技术的尽头，是工程哲学

后端不是炫技的舞台，而是系统稳定运行的基石。 写后端需要克制：克制过度抽象、克制灵感爆发、克制自由发挥。

因为：

• 稳定的系统靠“可预测性”；
• 长期的团队靠“约束”；
• 真正的技术成熟，体现在“写得少，错得少”。

JS 让你飞得快，Go 让你落得稳。

而成熟的团队，懂得何时该飞，何时该稳。

这篇文档用尽量轻松的方式，带你把现在的主题体系从“为什么要这么做”一路串到“真实的代码是怎样运转的”。看完它，你就能在脑海里勾勒出这套系统的全过程：预设 → Token → CSS 变量 → 页面应用 → 生成脚本 → 运行时同步。

热身：从最简单的主题方案说起

开始前先回顾一下大家最容易想到的做法，帮助你把这套体系的“前世今生”串起来：

1. 字符串配置 Ant Design Theme ** **最初我们只需在 ConfigProvider 里写个对象：

   
   <ConfigProvider
     theme={{
       token: {
         colorPrimary: '#1677ff',
         colorBgLayout: '#f5f5f5',
       },
     }}
   >
   

   这种写法简单直观，但它只影响 Ant Design 组件，普通样式文件里的颜色、间距依旧得手动维护，一旦换主题就得处处搜字符串。

2. 引入一个 CSS 变量做兜底 ** **于是我们可能会想到在全局样式里写：

   :root {
     --app-primary: #1677ff;
   }
   

   **自己的组件可以用 **var(--app-primary)，比硬编码好一点。但变量少、结构散乱，随着主题变多还是会失控：不同文件各自声明变量、缺乏注释、没有类型提示，团队协作很快陷入混乱。

3. 需求升级，开始寻找系统化思路 ** **当需要支持多套主题、明暗模式、甚至运行时切换时，就不得不思考：

   • **这些颜色、尺寸到底从哪来？ **
   • **Ant Design 的 token 怎么复用到我们的样式里？ **
   • 有没有办法让主题列表、变量名称都能自动补全，减少低级错误？

带着这些痛点，我们才走向下一节——打造一套类型化、自动化、统一管理的主题体系。

1. 目标：为什么要这么折腾？

1. 告别硬编码：以前的 SCSS 变量写死在文件里，换主题得全局搜一遍。现在把基础设计变量全部放进 TypeScript，让 IDE 帮我们补全并提示错误。
2. 统一管理：一份预设数据 + 一套生成脚本，就能衍生出所有模式（Light / Dark）与项目自定义主题，不再担心某个文件忘记更新。
3. 类型安全：Token 名称、CSS 变量名、DOM 属性统统“有类型”，手残都打不出错误的变量名。
4. 扩展友好：未来要加新主题、变更 Token、添加动态变换逻辑（transform）都很容易，只改一处即可触发全链路联动。

2. 数据源：主题预设（src/theme/tokens.ts）

最核心的就是定义好“主题预设”：

// src/theme/tokens.ts
import type { SeedToken } from 'antd/es/theme/interface';

type TRequiredSeedTokenKeys = 'colorPrimary' | 'colorInfo';
type TThemeAppearance = 'light' | 'dark';

type TThemeSeedOverrides = Pick<SeedToken, TRequiredSeedTokenKeys> &
  Partial<SeedToken>;

export interface IThemePreset<K extends string = string> {
  key: K;
  name: string;
  description: string;
  colors: Record<TThemeAppearance, string>;
  token: Record<TThemeAppearance, TThemeSeedOverrides>;
}

const createThemePreset = <K extends string>(preset: IThemePreset<K>) => preset;

export const THEME_PRESETS = [
  createThemePreset({
    key: 'shadcn',
    name: 'Shadcn',
    description: 'Shadcn 主题',
    colors: {
      light: 'oklch(12.9% 0.042 264.695)',
      dark: 'oklch(78% 0.042 264.695)',
    },
    token: {
      light: {
        colorPrimary: 'oklch(12.9% 0.042 264.695)',
        colorInfo: 'oklch(12.9% 0.042 264.695)',
      },
      dark: {
        colorPrimary: 'oklch(78% 0.042 264.695)',
        colorInfo: 'oklch(78% 0.042 264.695)',
      },
    },
  }),
  createThemePreset({
    key: 'purple',
    name: '酱紫 Purple',
    description: '艺术设计、创意类项目',
    colors: {
      light: '#722ed1',
      dark: '#9b6df0',
    },
    token: {
      light: {
        colorPrimary: '#722ed1',
        colorInfo: '#722ed1',
      },
      dark: {
        colorPrimary: '#9b6df0',
        colorInfo: '#9b6df0',
      },
    },
  }),
] as const;

export type TThemeKey = (typeof THEME_PRESETS)[number]['key'];

然后我们把它整理成一个 Map，方便查找：

export const THEME_MAP = THEME_PRESETS.reduce((acc, preset) => {
  acc[preset.key] = preset;
  return acc;
}, {} as Record<TThemeKey, IThemePreset>);

// 使用示例
const selected = useAppStore((state) => state.themeKey);
const themePreset = THEME_MAP[selected];

• colors.light / colors.dark 提供主题面板展示色，切换模式时色块同步更新；
• token[light] / token[dark] 喂给 Ant Design 生成完整 MapToken，保障组件主色一致；
• 如果只配置了 light，生成脚本会自动退回该值作为所有模式的默认。

好处：新增主题时有范可循，缺字段直接在编译阶段报错。

3. CSS 变量映射（src/theme/cssVariables.ts）

这个文件是整个改造的核心，做了几件事：

1. 定义常量：

   // src/theme/cssVariables.ts
   export const THEME_ATTRIBUTE = 'data-theme-key';
   export const THEME_MODE_ATTRIBUTE = 'data-theme-mode';
   export const THEME_MODES = ['light', 'dark'] as const;
   export type TThemeDomMode = (typeof THEME_MODES)[number];
   

   页面和脚本都用同一个常量，不怕手写拼错。

2. 分组列出所有要生成的 CSS 变量：

   const COLOR_VARS = defineCssVars(
     [
       { name: '--app-color-primary', token: 'colorPrimary', description: '主色' },
       { name: '--app-color-link', token: 'colorLink', description: '链接色' },
       { name: '--app-color-text', token: 'colorText', description: '文本色' },
     ] as const,
   );
   
   const BACKGROUND_VARS = defineCssVars(
     [
       { name: '--app-bg-layout', token: 'colorBgLayout', description: '布局背景色' },
       { name: '--app-color-fill', token: 'colorFill', description: '填充色' },
     ] as const,
   );
   
   export const CSS_VARIABLE_TOKEN_MAPPINGS = [
     ...COLOR_VARS,
     ...BACKGROUND_VARS,
   ] as const;
   

   defineCssVars + as const + satisfies 保留了变量名、映射 token 的字面量信息，后面 TypeScript 就能推导出 TCssVarName。

3. 静态变量同样类型化：

   export const STATIC_CSS_VARIABLES = defineStaticVars([
     { name: '--app-layout-header-height', value: '64px', description: '头部高度' },
     // ...
   ]);
   export type TStaticCssVarName = (typeof STATIC_CSS_VARIABLES)[number]['name'];
   

   这些变量不随主题变化，但我们让它们也有注释、有类型。

4. 辅助函数：** ** buildThemeSelector(presetKey, mode) 可以返回 :root[data-theme-key='purple'][data-theme-mode='dark']，脚本直接拿来用。

好处：

• **任何地方需要 **--app-color-primary 都能自动补全；
• **新增变量时顺手填 **description，生成的 CSS 会带上注释，便于 DevTools 快速了解用途；
• 静态变量和动态变量全部集中管理，真正做到“一本账”。
• 生成出来的 CSS 样子也更清晰，例如：

  :root[data-theme-key='purple'][data-theme-mode='light'] {
    /* 主色 */
    --app-color-primary: #722ed1;
    --app-color-link: #722ed1;
    /* 布局背景色 */
    --app-bg-layout: #f5f5f5;
  }
  

4. 运行时代码（src/utils/theme.ts & src/App.tsx）

src/utils/theme.ts

• resolveThemeMode(themeMode, systemPrefersDark)：把 store 里的 “light / dark / system” 转成真正的 light 或 dark。

  export const resolveThemeMode = (
    mode: TThemeMode,
    systemPrefersDark: boolean,
  ): TResolvedThemeMode => {
    if (mode === 'dark') return 'dark';
    if (mode === 'light') return 'light';
    return systemPrefersDark ? 'dark' : 'light';
  };
  

• ThemeDom.apply(root, key, mode)：往 <html>（我们用 document.documentElement）写入 data-theme-key 和 data-theme-mode；clear 用来卸载时清理。

  export const ThemeDom = {
    apply(root: HTMLElement, key: string, mode: TResolvedThemeMode) {
      root.setAttribute(THEME_ATTRIBUTE, key);
      root.setAttribute(THEME_MODE_ATTRIBUTE, mode);
    },
    clear(root: HTMLElement) {
      root.removeAttribute(THEME_ATTRIBUTE);
      root.removeAttribute(THEME_MODE_ATTRIBUTE);
    },
  };
  

• getCssVar(name, fallback)：

  export const getCssVar = <TName extends TCssVarName | TStaticCssVarName>(
    name: TName,
    fallback = '',
  ): string => {
    if (typeof document === 'undefined') return fallback;
    const value = getComputedStyle(document.documentElement)
      .getPropertyValue(name)
      .trim();
    return value.length > 0 ? value : fallback;
  };
  

  • **支持类型联合 **TCssVarName | TStaticCssVarName；
  • **使用 **getComputedStyle 拿最终样式；
  • **没有值就返回 **fallback。

src/App.tsx

• **读取 store 中的主题 key / 模式，配合 **resolveThemeMode 算出最终模式；
• **通过 **useEffect 调用 ThemeDom.apply，DOM 与 store 始终保持同步：

  const resolvedMode = resolveThemeMode(themeMode, systemPrefersDark);
  
  useEffect(() => {
    setResolvedThemeMode(resolvedMode);
    if (typeof document === 'undefined') return;
    const root = document.documentElement;
    ThemeDom.apply(root, themePreset.key, resolvedMode);
    return () => ThemeDom.clear(root);
  }, [resolvedMode, themePreset.key, setResolvedThemeMode]);
  

• ConfigProvider 使用主题预设中的 token，Ant Design 组件自动跟着换色：

  <ConfigProvider
    theme={{
      algorithm: resolvedMode === 'dark' ? darkAlgorithm : defaultAlgorithm,
      token: {
        colorPrimary: themePreset.token[resolvedMode].colorPrimary,
        colorInfo: themePreset.token[resolvedMode].colorInfo,
      },
    }}
  >
    <AntdApp>{/* ... */}</AntdApp>
  </ConfigProvider>
  

• **主题设置面板可以使用 **preset.colors[resolvedMode] 作为预览色块：

  const swatch = themePreset.colors[resolvedMode] ?? themePreset.colors.light;
  <span style={{ background: swatch }} className={styles['theme-swatch']} />
  

• ThemeDom.clear 确保热更新或卸载时不会留下陈旧属性。

好处：主题切换的状态流转完全可控，既更新 UI，又更新 DOM 属性，CSS 变量自然生效。

5. 生成脚本（scripts/generate-css-variables.ts）

核心逻辑非常集中，可以用这段代码概括：

const formatThemeBlocks = (): string => {
  const blocks: string[] = [];

  for (const mode of THEME_MODES) {
    const algorithm = ALGORITHMS[mode];
    for (const preset of THEME_PRESETS) {
      const seedOverrides =
        preset.token[mode] ?? preset.token.light ?? preset.token.dark;
      const seed = { ...defaultSeed, ...seedOverrides };
      const mapToken = algorithm(seed);

      const declarations = CSS_VARIABLE_TOKEN_MAPPINGS.map(({ name, token, description }) => {
        const rawValue = mapToken[token];
        const comment = description ? `${INDENT}/* ${description} */\n` : '';
        return `${comment}${INDENT}${name}: ${String(rawValue)};`;
      });

      const selector = buildThemeSelector(preset.key, mode);
      blocks.push(`${selector} {\n${declarations.join('\n')}\n}`);
    }
  }

  return blocks.join('\n\n');
};

**执行 **npm run generate:css-vars 后，就会得到包含所有主题/模式变量的 src/styles/generated/theme-variables.css，暗色模式也会使用你在预设里定义的专属主色。

• **如果某个主题没有提供特定模式的 seed，脚本会依次回退到 **light 或 dark 的配置，避免生成空值。

好处：

• 任何变量增加/删除只动这一个 TypeScript 文件；
• 生成文件带注释，方便排查；
• 有重复变量名会直接抛错，避免覆盖。

6. 样式引用（src/styles/global.scss 等）

• **统一使用 **var(--app-xxx) 提取主题色；
• **通过 **npm run generate:css-vars 产生的 CSS 被 src/main.tsx 引入；
• **页面结构中的具体样式（如 **AdminLayout.module.scss）只负责消费这些变量，不关心它们如何生成。

/* src/styles/global.scss */
:root {
  --layout-bg: var(--app-color-bg-layout);
  --text-color: var(--app-color-text);
  --card-border-color: var(--app-color-border-secondary);
}

[data-theme-mode='dark'] {
  color-scheme: dark;
}

/* src/layouts/AdminLayout.module.scss */
.admin-layout__theme-option {
  background: var(--card-bg);
  border: 1px solid var(--card-border-color);
  &:hover {
    border-color: color-mix(in srgb, var(--app-color-primary) 40%, transparent);
  }
}

好处：把“主题”这件事变成模块化的基础设施，新增页面只管引用变量，实现风格统一与换肤自如。

7. 常见操作流程

1. 新增主题

   • **在 **THEME_PRESETS 里加一项，同时补全 colors.light/dark 与 token.light/dark；
   • npm run generate:css-vars → 得到新主题下的 CSS 变量；
   • 重启/刷新即可使用。

2. 新增 CSS 变量

   • **在 **cssVariables.ts 对应分组里补一行；
   • 需要的话在组件/样式中引用这个新变量；
   • 跑生成脚本即可。

3. 读取变量值

   import { getCssVar } from '@/utils/theme';
   
   const primary = getCssVar('--app-color-primary', '#1677ff');
   const headerHeight = getCssVar('--app-layout-header-height', '64px');
   

   • 如果变量不存在会返回你传入的默认值。

8. 这套流水线的好处总结

• 统一入口：所有主题数据和变量都在 src/theme 下维护，清晰可控。
• 类型守护：TThemeKey、TCssVarName、TStaticCssVarName 等类型让 TS 帮你防止拼写错误。
• 自动生成：脚本帮你把 Antd Token 转成 CSS 变量，不需要手动写多份颜色/布局参数。
• 扩展简单：未来要实现 transform、modeScope 或更多模式，只要在映射里新增字段，脚本就能处理。
• 易于协作：有了注释、分组、文档，后续同事加入项目也能快速理解主线。

9. 推荐的命令清单

**建议在修改主题相关逻辑后，至少执行一次 **generate:css-vars + build，确保链路完整无误。

10. 接下来还可以做什么？

• **编写简单的 lint 脚本，检测样式文件里使用的 **var(--xxx) 是否都存在于类型定义中；
• 补充 transform / modeScope（之前预留的字段）以支持特殊处理，如暗色模式下再加一层透明度；
• 把 THEME_PRESETS 和 CSS 变量映射拆成更细的模块，编写 Storybook 文档展示主题效果。

只要按照上面的流程维护，你就拥有了一套健壮、可扩展、可协作的主题解决方案。祝玩得开心！

今天，让我来分享一下自己对于 React i18n 的理解，并使用核心 lib: i18next和 react-i18next从零开始配置解决方案。

react-i18next 版本为：16.1.5，因此相关文档需要看 LeGACY v9 的部分：https://react.i18next.com/legacy-v9/step-by-step-guide

前者是一个与框架无关的国际化库，无论 nodejs 和浏览器端都可以在工程化中使用。后者是 React 的适配层，且是基于 i18next的绑定层，有了它我们就可以在 React中轻松添加 i18n 支持。

项目仓库：AaronConlon/react-i18n-best-practice

目标

我的 i18n 方案实现了以下若干需求：

• 常规多语言切换
• 语言选择持久化
• 浏览器语言检测
• 大型项目：resource 拆分和命名空间管理
• TypeScript 项目下，翻译函数支持完善的自动补全
• 翻译文件懒加载，仅在需要的地方加载最小化翻译文件，并且让 i18next 支持 Suspense
• 翻译文件一致性检测脚本

行动

准备工作

1. 使用 rsbuild 的命令，初始化一个 react 19 项目，选择支持 TypeScript 即可
2. 安装 i18n libs
   1. react-i18next
   2. i18next
3. 安装 @tanstack/react-router 和 @tanstack/router-plugin，并且根据文档添加 rsbuild 配置来启用 react-router
4. 根据 https://github.com/TanStack/router/tree/main/examples/react/quickstart-rspack-file-based 这个例子，配置好可运行的环境

常规多语言及切换

先看看项目目录结构：

.
├── node_modules
├── package.json
├── README.md
├── rsbuild.config.ts
├── src
│   ├── App.tsx
│   ├── env.d.ts
│   ├── i18n.ts
│   ├── index.tsx
│   ├── routes
│   │   ├── __root.tsx
│   │   ├── about.tsx
│   │   └── index.tsx
│   ├── routeTree.gen.ts
│   ├── styles.css
│   └── utils
├── tsconfig.json
└── yarn.lock

首先创建 src/i18n.ts初始化文件：

import i18n from "i18next";
import { initReactI18next } from "react-i18next";

const resources = {
  // 语言
  en: {
    // 默认命名空间
    translation: {
      "Welcome to React": "Welcome to React and react-i18next",
    },
  },
  fr: {
    translation: {
      "Welcome to React": "Bienvenue à React et react-i18next",
    },
  },
};

i18n.use(initReactI18next).init({
  resources,
  // 默认语言
  lng: "en",
  // 备用语言
  fallbackLng: "en",
  // 插值方式
  interpolation: {
    // 不转义 html 标签，避免 XSS 攻击
    escapeValue: false,
  },
});

export default i18n;

并且在 src/index.tsx中引入：

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
// 导入，初始化 i18n
import "./i18n";

const rootEl = document.getElementById("root");

if (rootEl) {
  const root = ReactDOM.createRoot(rootEl);
  root.render(
    <React.StrictMode>
      <App />
    </React.StrictMode>
  );
}

然后看看 routes下的几个路由文件：

__root.tsx

import { createRootRoute, Link, Outlet } from "@tanstack/react-router";
import { useTranslation } from "react-i18next";

const RootLayout = () => {
  const { i18n } = useTranslation();

  return (
    <>
      <div className="header">
        <Link to="/" className="header-link">
          Home
        </Link>{" "}
        <Link to="/about" className="header-link">
          About
        </Link>
        {/* language selector */}
        <select
          className="language-selector"
          value={i18n.language}
          onChange={(e) => i18n.changeLanguage(e.target.value)}
        >
          <option value="en">English</option>
          <option value="fr">French</option>
        </select>
      </div>
      <Outlet />
    </>
  );
};

export const Route = createRootRoute({ component: RootLayout });

通过 useTranslation hook 可以得到 i18n实例，这个实例具有当前语言属性和修改语言的方法。

接下来看 src/routes/index.tsx的内容：

import { createFileRoute } from "@tanstack/react-router";
import { useTranslation } from "react-i18next";

export const Route = createFileRoute("/")({
  component: RouteComponent,
});

function RouteComponent() {
  const { t } = useTranslation();
  return <div className="content">{t("Welcome to React")}</div>;
}

还是核心 hook：useTranslation，通过 t函数传入翻译资源的字段来读取翻译的结果。

如上所示是 react-i18next 最常规的使用方法，还有几种写法和在 react 组件外获取翻译内容，有兴趣可以去看文档

现在，在 /路由下点击语言切换即可看到效果：

英语：

法语

语言持久化和语言检测

如果仅需实现持久化，则简单在 i18n.ts这里直接将硬编码的默认语言改为从 localStorage 或 cookie 里读取即可，如此一来既可以让后端接口返回自动修改用户语言，也可以在修改语言的时候将选择的语言保存到本地。

我个人更喜欢另一种方案：i18next-browser-languagedetector插件，根据用户浏览器的语言来设置默认语言！

首先，安装好插件：

yarn add i18next-browser-languagedetector 

然后再修改 i18n.ts初始化逻辑（忽略部分代码）：

import detector from "i18next-browser-languagedetector";

i18n
  .use(detector)
  .use(initReactI18next)
  .init({
    resources,
    // 备用语言
    fallbackLng: "en",
    // 插值方式
    interpolation: {
      // 不转义 html 标签，避免 XSS 攻击
      escapeValue: false,
    },
  });

测试的浏览器语言是中文，因此在代码里加上中文相关的 resource 翻译和 select option 即可。

此时，浏览器的 localStorage 里会自动加上 i18nextLng ，其值为 zh。

i18next-browser-languagedetector 选择语言的默认优先级如下：

• cookie
• localStorage
• navigator
• querystring (append ?lng=LANGUAGE to URL)
• htmlTag
• path
• subdomain

因此，笔者建议将语言选项的值保存到 cookie。

产品应该减少用户的操作，并且提供一种“顺畅”的用户体验。

大型项目：resource 拆分和命名空间管理

企业级项目代码量较为庞大，将 resource 翻译的代码写在 i18n.ts里实在是太过拥挤，因此我们必须将这些翻译资源拆分到不同的模块下，通过 json 的格式保存，再统一导入。

看代码：

import i18n from "i18next";
import detector from "i18next-browser-languagedetector";
import { initReactI18next } from "react-i18next";
import cn from "./locales/cn.json";
import en from "./locales/en.json";
import fr from "./locales/fr.json";

const resources = {
  en: {
    translation: en,
  },
  fr: {
    translation: fr,
  },
  cn: {
    translation: cn,
  },
};

i18n
  .use(detector)
  .use(initReactI18next)
  .init({
    resources,
    // 备用语言
    fallbackLng: "en",
    // 插值方式
    interpolation: {
      // 不转义 html 标签，避免 XSS 攻击
      escapeValue: false,
    },
  });

export default i18n;

首先，我们将翻译资源统一放在 src/locales下，按语言命名通过 json 导入，然后赋值给 translation（默认命名空间）。

当项目进一步扩大之后，翻译 json 文件将会变得越来越大，无论是查找还是修改都非常麻烦（在一个超大 json 文件中增删改查）。这时候，我们可以将翻译文件分为若干模块：

• Common (通用)
• User（用户页面）
• Dashboard（看板页面）

这时候我们可以在 locales下创建多语言目录，并且在目录内创建若干个命名空间对应的 json文件：

.
├── en
│   ├── common.json
│   ├── dashboard.json
│   └── user.json
├── fr
│   ├── common.json
│   ├── dashboard.json
│   └── user.json
└── zh
    ├── common.json
    ├── dashboard.json
    └── user.json

举例 zh/common.json：

{
  "welcome": "欢迎",
  "loading": "加载中...",
  "error": "错误",
  "success": "成功"
}

在组件中通过命名空间使用：

import { createFileRoute } from "@tanstack/react-router";
import { useTranslation } from "react-i18next";

export const Route = createFileRoute("/")({
  component: RouteComponent,
});

function RouteComponent() {
  const { t } = useTranslation(["common", "user", "dashboard"]);
  return (
    <div className="content">
      {/* common namespace */}
      <div className="common">{t("common:welcome")}</div>
      <div className="common">{t("common:loading")}</div>
      <br />
      {/* user namespace */}
      <div className="user">{t("user:profile")}</div>
      {/* dashboard namespace */}
      <div className="dashboard">{t("dashboard:overview")}</div>
    </div>
  );
}

这里的钩子函数参数非常关键：useTranslation(["common", "user", "dashboard"])，不同的参数会设置不同的默认命名空间，当设置了默认命名空间的时候，就可以在 t()函数里缺省命名空间前缀。

例如：

import { createFileRoute } from "@tanstack/react-router";
import { useTranslation } from "react-i18next";

export const Route = createFileRoute("/")({
  component: RouteComponent,
});

function RouteComponent() {
  const { t } = useTranslation(["common"]);
  return (
    <div className="content">
      {/* common namespace */}
      <div className="common">{t("common:welcome")}</div>
      <div className="common">{t("loading")}</div>
      <br />
      {/* user namespace */}
      <div className="user">{t("user:profile")}</div>
      {/* dashboard namespace */}
      <div className="dashboard">{t("dashboard:overview")}</div>
    </div>
  );
}

直接写 t("loading")是可以得到翻译结果的，因为指定了 common命名空间。此时如果你写 t("profile")，那么是得不到翻译结果的。

如果不传参给 useTranslation，那么就会从 i18n.ts里的默认命名空间去寻找翻译结果。

函数 t()根据传入的 key 去获取翻译自有一套规则，并且可能会根据版本变化而更新。

与其花时间去折腾其规则，不如创建多个指定命名空间且名字不同的 t函数，亦或者统一在 t()函数传参的时候写明命名空间。

import { createFileRoute } from "@tanstack/react-router";
import { useTranslation } from "react-i18next";

export const Route = createFileRoute("/")({
  component: RouteComponent,
});

function RouteComponent() {
  const { t } = useTranslation();
  const { t: tUser } = useTranslation("user");
  const { t: tDashboard } = useTranslation("dashboard");
  return (
    <div className="content">
      {/* common namespace */}
      <div className="common">{t("welcome")}</div>
      <div className="common">{t("loading")}</div>
      <br />
      {/* user namespace */}
      <div className="user">{tUser("profile")}</div>
      {/* dashboard namespace */}
      <div className="dashboard">{tDashboard("overview")}</div>
    </div>
  );
}

TypeScript 编写体验优化

如果你也使用 TypeScript 编写 React 代码，那么我想你会喜欢在使用 t()函数的时候填写 key获得编辑器的自动提示支持。

实现方案如下：

• 微调 i18n.ts文件
• 创建 src/i18next.d.ts类型声明文件

首先来看新的 i18n.ts文件：

import i18n from "i18next";
import detector from "i18next-browser-languagedetector";
import { initReactI18next } from "react-i18next";
import zhCommon from "./locales/zh/common.json";
import zhDashboard from "./locales/zh/dashboard.json";
import zhUser from "./locales/zh/user.json";

import enCommon from "./locales/en/common.json";
import enDashboard from "./locales/en/dashboard.json";
import enUser from "./locales/en/user.json";

import frCommon from "./locales/fr/common.json";
import frDashboard from "./locales/fr/dashboard.json";
import frUser from "./locales/fr/user.json";

export const defaultNS = "common";

export const resources = {
  en: {
    common: enCommon,
    user: enUser,
    dashboard: enDashboard,
  },
  fr: {
    common: frCommon,
    user: frUser,
    dashboard: frDashboard,
  },
  zh: {
    common: zhCommon,
    user: zhUser,
    dashboard: zhDashboard,
  },
} as const;

i18n
  .use(detector)
  .use(initReactI18next)
  .init({
    resources,
    ns: ["common", "user", "dashboard"],
    defaultNS,
    // 备用语言
    fallbackLng: "en",
    // 插值方式
    interpolation: {
      // 不转义 html 标签，避免 XSS 攻击
      escapeValue: false,
    },
  });

export default i18n;

变化在于：

• 将默认命名空间导出
• 将 resource 导出，并且在末尾使用 as const来让 TypeScript 断言，告诉编译器这个对象缩窄后的类型。

再看类型声明文件：i18next.d.ts:

import { defaultNS, resources } from "./i18n";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: typeof defaultNS;
    resources: {
      common: (typeof resources)["en"]["common"];
      user: (typeof resources)["en"]["user"];
      dashboard: (typeof resources)["en"]["dashboard"];
    };
  }
}

给 module i18next的 CustomTypeOptions接口声明默认命名空间和 resource 的类型，如此一来就可以在 t()这里自动补全 key了。

JSON 懒加载

直接通过 import语句导入 json文件，在打包的时候会把全部翻译资源打包到代码中去，显著增加 bundle尺寸。

在开始之前，明确自己的场景和需求，回答以下几个问题：

• 能否需要 CDN
• 是否限制 Bundle 体积
• 是否运行于不稳定的网络
• 是否离线运行
• 是否需要严格确保加载资源的可用性

得出答案之后，我们逐一分析以下场景选择的技术栈和实现方案：

国内企业中后台（React SPA）

通常企业后台对 SEO、首屏加载速度、弱网和离线、强可用都要求不高，选择 i18next-resources-to-backend插件足以。

import i18n from "i18next";
import detector from "i18next-browser-languagedetector";
import resourcesToBackend from "i18next-resources-to-backend";
import { initReactI18next } from "react-i18next";

i18n
  .use(detector)
  .use(
    resourcesToBackend(
      (lang: string, ns: string) => import(`./locales/${lang}/${ns}.json`)
    )
  )
  .use(initReactI18next)
  .init({
    ns: ["common"],
    defaultNS: "common",
    // 备用语言
    fallbackLng: "en",
    // 插值方式
    interpolation: {
      // 不转义 html 标签，避免 XSS 攻击
      escapeValue: false,
    },
  });

export default i18n;

所有初始化时设置的 ns都会在首次加载直接请求对应的 chunk文件，如上所示我的测试环境会立即请求：

http://localhost:3000/static/js/async/src_locales_en_common_json.js

回过头来看，我们的目标还有一个 React Suspense 特性需要支持。为什么要这个特性？在本地开发的时候资源加载极快，你可能一不小心没注意到翻译的结果会出现闪烁，究其原因在于 i18next-react 在初次渲染的时候还没有获取到翻译的资源，于是会立即渲染对应的 key 的字符串内容。

所以，我们应该在这个阶段提供特定的 UI 来防止闪烁，看看如下代码：

import { createRootRoute, Link, Outlet } from "@tanstack/react-router";
import { useTranslation } from "react-i18next";

const RootLayout = () => {
  const { i18n, t } = useTranslation("menu");

  return (
    <>
      <div className="header">
        <Link to="/" className="header-link">
          {t("home")}
        </Link>{" "}
        <Link to="/about" className="header-link">
          {t("about")}
        </Link>
        <Link to="/test" className="header-link">
          {t("test")}
        </Link>
        {/* language selector */}
        <select
          className="language-selector"
          value={i18n.language}
          onChange={async (e) => {
            const newLang = e.target.value;
            // save to cookie
            // document.cookie = `i18nextLng=${newLang}; path=/`;
            await i18n.changeLanguage(newLang);
          }}
        >
          <option value="en">English</option>
          <option value="fr">French</option>
          <option value="zh">中文</option>
        </select>
      </div>
      <Outlet />
    </>
  );
};

export const Route = createRootRoute({
  component: RootLayout,
  pendingComponent: () => (
    <div className="loading">Loading at root layout...</div>
  ),
});

在创建路由这里添加一个 Suspense fallback（pendingComponents），即可在渲染 RootLayout 组件的时候，让内部逻辑触发 Suspense 边界条件，从而渲染 loading 内容。

rsbuild会将这个 json 文件打包成一个独立的 js文件，此外上述配置还加上了 react use suspense 支持：

{
  react: {
    useSuspense: true,
  }
}

现在，初始化加载语言翻译资源会触发 Suspense fallback 了！当然，上述代码仅在初始化的时候会渲染 fallback，初始化完成后再次切换语言将会请求新的语言翻译 chunk，此时不会触发 Suspense fallback，针对这一点我们可以单独使用 useTransition或者单独维护一个 loading 状态，在 Outlet组件下方渲染独立的 Loading Mask 组件（和 pendingComponent 共用）。

出海应用 + 独立服务器部署（React SPA）

独立服务器意味着资源存放在服务器这里，出海应用的用户可能来自不同的国家和地区，这时候使用 CDN 存放 JSON 翻译资源可以加快初始化和更换语言的速度。

使用 i18next-resources-to-backend依然可以做到这一点，不过我们需要将 import语句修改为 fetch远程 json 资源的逻辑。但是这一步细化一下也有一些问题需要处理，例如：缓存控制和版本处理、出错处理。

在这里我们需要考虑一个问题：翻译 JSON 文件是否需要在 Build 阶段构建成 js chunk，亦或是将翻译资源独立出来，存放在 OSS 上，利用 CDN 的能力提速，同时还可以灵活更新 OSS 文件，让应用不需要耗时构建整个应用。

有一个插件能很好地处理这个需求：i18next-http-backend，其核心是：让语言包成为“外部资源”，让国际化系统想加载数据一样加载翻译。

import i18n from "i18next";
import detector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";
import { initReactI18next } from "react-i18next";

i18n
  .use(detector)
  .use(HttpBackend)
  .use(initReactI18next)
  .init({
    backend: {
      loadPath:
        import.meta.env.PUBLIC_I18N_PATH + "locales/{{lng}}/{{ns}}.json",
      crossOrigin: true,
      queryStringParams: {
        v: import.meta.env.PUBLIC_I18N_VERSION,
      },
    },
    ns: ["common", "menu"],
    defaultNS: "common",
    // 备用语言
    fallbackLng: "en",
    // 插值方式
    interpolation: {
      // 不转义 html 标签，避免 XSS 攻击
      escapeValue: false,
    },
    react: {
      useSuspense: true,
    },
  });

export default i18n;

其核心在于配置项：

backend: {
  loadPath:
    import.meta.env.PUBLIC_I18N_PATH + "locales/{{lng}}/{{ns}}.json",
  crossOrigin: true,
  queryStringParams: {
    v: import.meta.env.PUBLIC_I18N_VERSION,
  },
}

现在，我们可以将 /locales 目录移动到 public 下

我们通过环境变量去设置翻译文件的来源，在开发模式下读取'/'（public）的翻译文件，在生产环境读取 CDN 地址的资源。

如果项目复杂，我们也可以通过 API 获取用户更多信息，在这里修改其翻译资源的来源和版本等配置。

在用户请求 CDN 资源的时候，指定 queryStringParams 中的对象，通过这个机制来控制缓存，CDN 服务器根据 URL 来区分是否返回缓存，当然浏览器也一样。

我们可以通过一个 API 后端服务来统一下发用户的资源版本号和 CDN 地址（如果有必要的话），这个后端 API 既可以是独立于不同项目的，也可以是这个项目下配合的后端服务。

如果想做灰度测试，或者通过某个用户来测试线上环境的翻译效果，则可以单独给这个用户增加版本，从而触发用户浏览器缓存失效，最终从用户浏览器，经过 CDN 服务器，最终回源到 OSS 去请求最新的文件。

离线应用、桌面应用、内网应用

假设开发一个离线应用，亦或是可以读取到载体的文件系统的应用，我们可以将翻译资源通过主动下载的方式保存到用户的设备。

我们可以选择这个插件：i18next-fs-backend

import i18n from 'i18next'
import FsBackend from 'i18next-fs-backend'
import { initReactI18next } from 'react-i18next'
import path from 'path'
import { fileURLToPath } from 'url'

// __dirname 兼容 ESM
const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)

// 语言文件目录（绝对路径）
const localesPath = path.join(__dirname, './locales')

i18n
  .use(FsBackend)
  .use(initReactI18next)
  .init({
    backend: {
      loadPath: path.join(localesPath, '{{lng}}/{{ns}}.json'),
    },
    lng: 'zh',                 // 默认语言
    fallbackLng: 'en',
    ns: ['common', 'dashboard'],
    defaultNS: 'common',
    interpolation: {
      escapeValue: false,      // React 已自动防 XSS
    }
  })

export default i18n

离线应用的语言 JSON 都从 fs 直接读取，不依赖 HTTP 也不需要 CDN。

如果是内网应用，则可以提供一个服务上传翻译资源，再通过 fs 写入到指定的目录。

这些插件的写法非常相似，切换起来很容易。

XXX 产品

假设...

• 产品用户来自不同地区，网络情况复杂无比
• CDN 服务不稳定，加钱也没用
• 甲方要求高，千万不能出错
• 翻译内容频繁需要更新

那么，我建议使用这个方案：

import i18n from 'i18next'
import Backend from 'i18next-chained-backend'
import LocalStorageBackend from 'i18next-localstorage-backend'
import HttpBackend from 'i18next-http-backend'
import resourcesToBackend from 'i18next-resources-to-backend'
import { initReactI18next } from 'react-i18next'

const CDN_PRIMARY = 'https://cdn1.yourcompany.com/locales'
const CDN_SECONDARY = 'https://cdn2.backupcdn.com/locales'
const LOCAL_VERSION = '2025.10.26' // 版本控制：可由 CI/CD 自动注入

i18n
  .use(Backend)
  .use(initReactI18next)
  .init({
    lng: 'zh',
    fallbackLng: 'en',
    ns: ['common', 'menu', 'dashboard'],
    defaultNS: 'common',
    backend: {
      // 1️⃣ 多层后端配置（顺序：缓存 → 主 CDN → 备 CDN → 本地 fallback）
      backends: [
        LocalStorageBackend,
        HttpBackend,
        HttpBackend,
        resourcesToBackend((lng, ns) => import(`../locales/${lng}/${ns}.json`)),
      ],
      backendOptions: [
        // --- LocalStorage 缓存层 ---
        {
          expirationTime: 7 * 24 * 3600 * 1000, // 缓存 7 天
          versions: {
            common: LOCAL_VERSION,
            menu: LOCAL_VERSION,
            dashboard: LOCAL_VERSION,
          },
        },
        // --- 主 CDN ---
        {
          loadPath: `${CDN_PRIMARY}/{{lng}}/{{ns}}.json`,
          crossDomain: true,
          queryStringParams: { v: LOCAL_VERSION },
        },
        // --- 备用 CDN ---
        {
          loadPath: `${CDN_SECONDARY}/{{lng}}/{{ns}}.json`,
          crossDomain: true,
          queryStringParams: { v: LOCAL_VERSION },
        },
        // --- 本地 fallback ---
        {}, // resourcesToBackend 不需要额外配置
      ],
    },
    interpolation: { escapeValue: false },
    react: { useSuspense: true },
  })

export default i18n

上述方案的功能如下：

• 多 CDN 容错 - 两个 httpBackend
• 持久化存储 - 优先从 localstorage 读取
• 本地 fallback - 构建阶段同样将翻译资源打包成 chunk
• 自动切换逻辑 - i18next-chained-backend按顺序执行

版本的控制和缓存更新可以参考之前提到过的方案（版本服务 API），多 CDN 的目标是让用户先从更稳定、更靠近用户的地方的服务商请求数据。

与此同时，应用也可以考虑支持一个清理换存的服务，让用户主动触发。

一致性检测

开发过程中修改翻译资源容易遗漏某个语言的信息，很有必要添加一个 script 在提交 Git 记录的时候提前检测翻译资源，以免字段没有对齐。

首先，添加相关 scripts 到 package.json 里：

{
  "scripts": {
    "check:i18n": "node scripts/check-i18n-consistency.js",
    "prepare": "husky install"
  }
}

创建在根目录的 scripts 目录下编辑 check-i18n-consistency.js:

#!/usr/bin/env node
/**
 * 检查 /locales/en/*.json 是否在其他语言下都有对应文件，
 * 并确保 JSON key 一致。
 */
import fs from "fs"
import path from "path"

const BASE_LANG = "en"
const LOCALES_DIR = path.resolve("./public/locales")

function getAllLangs() {
  return fs
    .readdirSync(LOCALES_DIR)
    .filter((f) => fs.statSync(path.join(LOCALES_DIR, f)).isDirectory())
}

function loadJson(filePath) {
  try {
    const content = fs.readFileSync(filePath, "utf8")
    return JSON.parse(content)
  } catch (e) {
    console.error(`❌ 无法解析 JSON 文件：${filePath}`)
    process.exit(1)
  }
}

function getJsonKeys(obj, prefix = "") {
  let keys = []
  for (const key in obj) {
    const full = prefix ? `${prefix}.${key}` : key
    if (typeof obj[key] === "object" && obj[key] !== null) {
      keys = keys.concat(getJsonKeys(obj[key], full))
    } else {
      keys.push(full)
    }
  }
  return keys
}

// ----------------- 主逻辑 -----------------
const langs = getAllLangs()
if (!langs.includes(BASE_LANG)) {
  console.error(`❌ 缺少基准语言目录：${BASE_LANG}`)
  process.exit(1)
}

const baseFiles = fs
  .readdirSync(path.join(LOCALES_DIR, BASE_LANG))
  .filter((f) => f.endsWith(".json"))

let hasError = false

for (const lang of langs.filter((l) => l !== BASE_LANG)) {
  console.log(`🔍 检查语言：${lang}`)

  for (const file of baseFiles) {
    const baseFile = path.join(LOCALES_DIR, BASE_LANG, file)
    const targetFile = path.join(LOCALES_DIR, lang, file)

    if (!fs.existsSync(targetFile)) {
      console.error(`❌ 缺少 ${lang}/${file}`)
      hasError = true
      continue
    }

    const baseJson = loadJson(baseFile)
    const targetJson = loadJson(targetFile)

    const baseKeys = getJsonKeys(baseJson)
    const targetKeys = getJsonKeys(targetJson)

    const missing = baseKeys.filter((k) => !targetKeys.includes(k))
    const extra = targetKeys.filter((k) => !baseKeys.includes(k))

    if (missing.length || extra.length) {
      console.error(`❌ ${lang}/${file} 键不一致:`)
      if (missing.length)
        console.error(`   缺少：${missing.join(", ")}`)
      if (extra.length)
        console.error(`   多余：${extra.join(", ")}`)
      hasError = true
    }
  }
}

if (hasError) {
  console.error("\n🚫 多语言文件结构不一致，请修复后再提交。")
  process.exit(1)
}

console.log("✅ 多语言文件检查通过！")
process.exit(0)

接着安装 husky并初始化：

yarn add -D husky
yarn husky install

创建 pre-commit 钩子：

mkdir -p .husky
touch .husky/pre-commit
chmod +x .husky/pre-commit

husky v9 版本更新之后，配置可能有所不同

编辑 pre-commit:

echo "✨ Running lint-staged and i18n check..."
yarn run check:i18n

上述 sh 脚本会在 git 提交的时候执行 check:i18n 这个命令，我们也可以在其他时候执行以下检查字段有没有对齐。

好了，让我们来检查一下是否顺利。

➜  react-i18n-best-practice git:(main) ✗ yarn check:i18n
yarn run v1.22.22
$ node scripts/check-i18n-consistency.js
🔍 检查语言：fr
🔍 检查语言：zh
✅ 多语言文件检查通过！
✨  Done in 0.96s.
➜  react-i18n-best-practice git:(main) ✗ 

将 locales/zh/common.json修改为：

{
  "welcome": "欢迎",
  "loading": "加载中...",
  "error": "错误",
  "successssss": "成功"
}

再提交 git 让 husky 检查一次：

➜  react-i18n-best-practice git:(main) ✗ gacm "chore: test husky"
✨ Running lint-staged and i18n check...
yarn run v1.22.22
$ node scripts/check-i18n-consistency.js
🔍 检查语言：fr
🔍 检查语言：zh
❌ zh/common.json 键不一致:
   缺少：success
   多余：successssss

🚫 多语言文件结构不一致，请修复后再提交。
error Command failed with exit code 1.

大功告成！

最后

好了，我的 React SPA 多语言方案大致已经梳理清楚了，如果你也有一些不同的见解，欢迎留言交流。

下一篇分析我将给大家带来 React SPA + Antd 的使用分析，通过其 token 机制制定多主题色系统，最终实现一个我们满意的风格。

本期精选 8 大亮点工具/项目，聚焦 AI、生产力和开发效率。以下以简洁列表呈现，帮助你快速定位：

• Haye (AI 助手)核心亮点：macOS 私有 AI，支持多模型聊天（GPT-4.1/Claude 等）、文件/网页互动
• OpenAI Codex (编码工具)核心亮点：GPT-5 驱动的编码代理，自动化 bug 修复/PR，CLI 集成
• X Profile Menu (浏览器插件)核心亮点：Chrome 插件，悬停 Profile 弹出“冲浪”菜单，开源
• Turso (数据库)核心亮点：LibSQL 基建，轻量云/本地存储，支持向量搜索，多语言 SDK
• Bing Wallpaper Today (资源站)核心亮点：4K 必应壁纸合集，多年高清下载
• npkill (清理工具)核心亮点：CLI 删除 node_modules，键盘一键节省空间
• Filo Mail (邮件服务)核心亮点：AI+Gmail，自动总结待办/翻译回信/续费提醒

Haye

haye 是一个私有 macOS AI 助手程序，使您可以在一个应用中体验到深层搜索 R1、GPT-4.1、o3、Clude-3.7 和 Gemini-2.5 等顶级模型。简单来说，可以让用户在 macOS 上聊天，支持任何应用程序、文本、截图、文件。

主要功能：

• 访问顶级 AI 模型：在一个应用中集成多个主流模型（如 Gemini、Claude、OpenAI、DeepSeek 和 Openrouter），支持同时与多个模型聊天并比较响应。
• 与桌面应用协作：无缝与 macOS 上的应用互动，适用于工作或学习任务。
• 网页搜索：连接互联网，提供快速、可信的答案，并附带相关网页来源链接。
• 与文件聊天：通过自然对话与 PDF 文档和本地文件互动，支持研究和内容理解。
• 便捷工具栏：使用简单快捷键快速查询文本和图像。

这个应用为用户提供了基本服务，同时支持一次性买断和月度订阅。

OpenAI Codex

Codex 是 OpenAI 推出的一系列 AI 编码工具，旨在帮助开发者通过云端和本地编码代理加速软件开发流程。它基于 GPT-5 等高级模型，专注于自动化编程任务，如编写功能、修复 bug、运行测试和提出拉取请求（PR）。

在 X 平台上，我看到很多开发者对 Codex 赞不绝口，并且认为其编程能力比 Claude 更强。Codex 可独立完成长任务，或与开发者互动；它模仿人类代码风格，并通过强化学习适应 PR 偏好。

只要你订阅了 ChatGPT Plus、Pro、Business、EDU 等计划即可使用，并且和 Claude 不同的是就算在 CLI 中使用完了阶段性的额度，也不会影响 web 端 Pro 等服务，并且其 Token 比 Claude 更加慷慨一些。

再加上 Claude 母公司对我们天然敌视（某种意义上），或许下个月我就要转投 Codex 了 🤣

X Profile Menu

X Profile Menu - Chrome 浏览器插件 是我开发的一款 chrome 插件，开发这个插件的目的是解决我一个推特冲浪需求：快速查看我喜欢的内容，甚至是创建一个独立的可随时查看的主页空间。

简单来说，即通过鼠标移动到 Profile 按钮上，弹出快捷菜单：

既可以快速跳转个人页面，也可以在当前页面打开一个独立的空间，随时冲浪。

代码我开源在：AaronConlon/x-profile-menu-expansion.，欢迎给我一个 Star 支持我~ 感谢！

Turso

tursodatabase/turso: Turso Database is a project to build the next evolution of SQLite.

Turso 是一个基于 LibSQL（Rust 重写的 SQLite 分支，完全兼容 SQLite）的数据库服务，支持异步 I/O 和向量搜索。这个团队同时提供开源版本和云服务，云服务的免费额度对于独立开发者来说足以开发一个小型应用的存储需求，非常适合验证性的服务。

其 SDK 支持以下语言：

• Go
• JavaScript
• Java
• Python
• Rust
• WebAssembly

对于轻量化的本地存储来说，绝对值得了解一下。

Bing 壁纸合集站点

Bing Wallpaper Today | Explore & Download Daily Wallpapers in 4K

Bing wallpaper today 是一个必应壁纸资源汇总网站，你可以在这里找到 4k 高清的最近几年的所有壁纸图片。

npkill

NPKILL - Maintain your development workspace clean.

npkill 是一个基于 nodejs 的命令行工具，它可以查看和清理指定目录下所有前端项目的 node_modules 目录，并且可以以一种非常简洁优雅的方式删除那些非必需的包，大大节省系统存储空间。

我们可以通过键盘快捷键轻松清理不需要的目录。

Filo Mail

Filo Mail - AI Email Client & To-Do：邮件诞生至今数十年，早已成为我们工作与生活的一部分，但它的核心体验，却始终未变。我们坚信，AI 时代的到来，正是重构这一重要工具的最佳时机。

Filo 是一个 Google Mail + AI 服务合二为一的邮箱服务，前几期我推荐过一次，今天再次推荐给大家。

因为我切身体会到 AI 加持后的邮箱服务的好处，Filo 及时分析我的邮件内容，给我总结了待办事项，让我及时查看重要邮件，实实在在的帮助了我。

其核心能力如下：

• 工作代办处理
• 订阅扣费续费警告
• 外文转译和辅助回信
• 内容总结

产品团队更新非常快，并且也有移动端支持。

Coomer

Coomer 是...兄弟们...这是一个为了世界和平而创建的网络资源共享平台，全世界的兄弟们都把好东西共享出来了 🤣

图

最后

我在网上看到这句话，送给大家：“AI不會取代你的工作，用AI的人會。”

Bye！下周见。

大家好，欢迎查收本周的周刊资讯 🎉，本周给大家介绍了 Claude Code、Context7、UpAir、Surf、Streamdown、Keka、Magecdn 和 Cap 等工具，涵盖编程、文件管理、隐私保护和 UI 优化，助力开发者提升效率。

Claude Code 概述

Claude Code 概述 - Anthropic

了解 Claude Code，Anthropic 的智能编程工具，它运行在您的终端中，帮助您比以往更快地将想法转化为代码。

如果你喜欢 Claude Code，那么非常建议浅浅阅读一遍这个概述文档，它能让你对 Claude Code 的功能和日常使用方式有一个更好的理解。

Claude Code 通知

在 Claude Code 编写代码的时候，我可能在发呆。那么如何让 claude 提醒我它已经搞定了呢？

我找到一个方法，逐步执行以下命令：

cd ~/.claude
vim settings.json

打开设置文件之后，将以下配置写入：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

重启 Claude Code 即可让其完成任务之后调用系统的提示音，叮一下我😄

Context7

Context7 - Up-to-date documentation for LLMs and AI code editors

Context7 是一个由 Upstash 开发的工具，主要用于为大型语言模型（LLM）和 AI 代码编辑器提供最新的、版本特定的代码文档和示例。

它通过索引官方文档（如 Next.js、Django、FastAPI 等框架），过滤并注入实时代码片段，帮助 AI（如 Claude）避免生成过时或错误的代码。Context7 支持手动复制粘贴，也可以通过 MCP（Model Context Protocol，模型上下文协议）服务器与 AI 工具集成，实现自动化注入文档。

在 Claude Code（Anthropic 的 Claude AI 代码生成工具）中使用 Context7 的核心优势是：Claude 可以动态查询最新文档，减少“幻觉”（hallucination）问题，例如生成已弃用的 API 或旧版本语法。

这特别适合 Python、JavaScript 等语言的开发，尤其在处理快速更新的库时。

UpAir

UpAir - 快速云存储上传工具，原生 APP 体积仅 500 kb

UpAir 是一款专为 macOS 用户打造的强大直观文件上传工具，支持拖拽上传、自动链接复制，让云文件分享变得简单快速。

仅需配置你的 AWS S3 或 Cloudflare R2 端点，然后拖放文件到应用或托盘，即可上传并且获取链接，自动复制到粘贴板。

📢：支持独立开发者，本软件内购一次性价格 28 RMB

Surf

enetx: g and surf

Surf 是一个用 Go 编写的高级浏览器仿真（surf）库/工具，目标是在网络请求层面尽可能真实地模仿 Chrome 与 Firefox 的客户端指纹与传输特征，从而提高隐私、防止指纹追踪或用于自动化测试与反爬场景下的更高隐蔽性。其主要特性：

• 浏览器伪装：支持 Chrome v131、Firefox v131 等多版本指纹
• JA3/JA4 指纹定制：完全自定义 TLS 握手特征
• HTTP/3 与 QUIC 支持：包含完整的 QUIC 传输参数指纹
• 中间件系统：可扩展的请求/响应处理链
• 连接池优化：单例模式实现高效连接复用
• 代理轮换：支持 HTTP、HTTPS、SOCKS5 代理自动切换

典型用例：

• 反指纹测试与安全评估：检测服务器或 WAF 对浏览器指纹的识别与响应。
• 高仿真自动化爬虫：在需要更高隐蔽性的自动化抓取（合规与合法场景）中使用。
• 接口/兼容性测试：模拟不同浏览器组合，测试后端对不同浏览器行为的兼容性。
• 隐私保护代理：作为中间代理，替客户端对外展示不同指纹以保护隐私。

Streamdown

Streamdown - 渲染流式 markdown 内容的神器

Streamdown 是一个 Vercel 团队为 AI 驱动的流媒体设计的 react-markdown 的掉入式替代品。

Streamdown包含内置的 Tailwind 类，用于常见 Markdown 组件 —— 标题、列表、代码块等等。

此外，这个库对数学公式的支持非常强大，如果你需要考虑支持数学公式，那么这个库可以大大节省你的开发时间。

流式返回的 AI 响应内容很多时候不是完整的 markdown 语法内容，常规的 react-markdown 无法渲染样式良好的 UI，这就是 Streamdown 发力的地方，使用这个库可以避免这个经典问题。

此外，Streamdown 还原生支持 GitHub 风味标记语言 (GFM)，因此您可以获得任务列表、表格等。

Streamdown 使用 Shiki 来突出显示代码块，并附带了一个复制按钮，这样您就可以轻松复制代码。鼠标悬停就能看到复制按钮！

让我们来看一个渲染 markdown 之中代码内容例子：

某种意义上，即使不需要渲染流式 markdown 也可以考虑这个库。

Keka

Keka - macOS 压缩文件管理器

对于普通苹果电脑用户来说，在 macOS 上找到一个好用且支持的格式齐全的文件压缩和解压工具并不容易。

Keka 是一款专为 macOS 设计的压缩和解压文件管理器，它在功能、易用性和扩展性上远超 macOS 自带的 Archive Utility（默认解压工具）。

主要优势概述更广泛的格式支持：

• Keka 支持解压 30+ 种格式，包括 RAR、7Z、ZIPX 等常见但 Archive Utility 不支持的类型；压缩格式也更丰富（如 DMG、ISO），适合处理各种来源的文件。
• 高级功能：提供加密、分卷压缩和批处理，增强安全性和实用性，而默认工具几乎没有这些。
• 用户友好界面：拖拽式操作、更直观的进度显示和集成选项，让日常使用更高效。 性能与兼容性：虽未明确量化速度，但其优化设计（如分卷处理大文件）在实际场景中更可靠，尤其对老旧 macOS 版本有历史支持。
• 免费与开源：Keka 免费下载（App Store 也有付费版），并可设置为系统默认工具，提升无缝体验

Magecdn

Open Source SVG Loading Icons

magecdn 免费提供 108 个可以自定义颜色的 SVG loading icon 下载使用

Cap

Cap — Modern, lightning-quick PoW captcha

Cap 是一个轻量化的人机验证工具，支持自托管部署，接入非常简单，可以在国内产品中使用。

出海的服务可以使用 Cloudflare Turnstile 或者 reCAPTCHA，但是国内真的没有好的免费的方案，什么极验之类都特别贵，完全可以用这个来代替一下。

图

最后

感谢阅读到此，大家下周再见 👋

1. Filo：一款AI驱动的邮件客户端，支持邮件管理和待办事项。
2. LimeWire：免费的文件传输网站，支持大文件传输和端到端加密。
3. CheckCle：实时监控工具，提供服务器、应用程序和基础设施的监控功能。
4. number-precision：一个轻量级（1k大小）的JavaScript库，用于精确的加减乘除操作。
5. Evil Charts：开源React图表组件，支持多种动画和图表类型。
6. Penpal：基于Promise改进iframe、Web Worker和窗口间通信的工具。
7. doocs/md：支持微信公众号样式预览的Markdown编辑器，提供多种自定义功能和AI助手。

Filo 邮至即成

邮件堆积成山？Filo 顺手理开：重点有了，待办好了，回复快了。

Filo Mail - AI Email Client & To-Do

暂时仅发布了 macOS 版本的客户端，无缝链接多个 Gmail 账户，将 AI 能力发挥到邮件里，自动将邮件内容总结、分析从而提取出可能的 Task 任务，也可以润色和辅助翻译、发送邮件。

其中有一个扣费邮件分析和提醒的功能倒是很有亮点，此外也支持移动端 APP 下载。

笔者使用一周下来体验很好，不过 AI 相关的能力笔者倒是暂时没有涉及。

Limewire 文件传输

笔者给朋友传送一个文件的需求如下：

• 不需要依赖任何需要注册登录的平台
• 至少能过传输 300M 文件
• 具有良好的传输速度

此前国内有奶牛快传可满足需求，自从他们的服务升级了之后就不再符合笔者的要求了，于是我找到了：LimeWire: Share Files - Secure File Upload Platform！

这是一个开放的免费文件传输网站，支持最大 4G文件或目录传输和下载（端到端加密）和其他AI 相关功能，需要用的朋友可以看看。

Checkcle.io

CheckCle - Self-Hosted Open Source Monitoring Tools for Real-time Servers & Applications

CheckCle 是一款开源解决方案，用于对全栈系统、应用程序和基础设施进行无缝实时监控。它为开发人员、系统管理员和 DevOps 团队提供其环境各层（无论是服务器、应用程序还是服务）的深入洞察和可操作数据。借助 CheckCle，你可以在整个技术堆栈中获得可见性、控制权以及确保最佳性能的能力。

服务可用性与基础设施/服务器监控

• 监控 HTTP、DNS 和 Ping 协议
• 监控基于 TCP 的服务与 API（如 FTP、SMTP、HTTP）
• 跟踪详细的可用性（正常运行时间）、响应时间与性能问题
• 分布式区域监控
• 事件历史（UP / DOWN / WARNING / PAUSE：上线 / 下线 / 警告 / 暂停）
• SSL 与域名监控（域名、签发者、到期日期、剩余天数、状态、上次通知）
• 基础设施与服务器监控：支持 Linux（🐧Debian、Ubuntu、CentOS、Red Hat 等）与 Windows（Beta）；提供 CPU、内存、磁盘使用、网络活动等服务器指标；一行命令安装的 Agent 脚本
• 维护计划与事件管理
• 运行状态 / 公共状态页
• 通过电子邮件、Telegram、Discord 和 Slack 通知
• 报告与分析
• 设置面板（用户管理、数据保留、多语言、主题〔深色/浅色模式〕、通知渠道与告警模板）

当前架构支持

• ✅ x86_64 PC、笔记本电脑、服务器 (amd64)
• ✅ 现代树莓派3/4/5（搭载64位操作系统）、Apple Silicon Macs (arm64)

应用截图如下，其实还挺适合需要监控多个服务器和应用的场景的：

number-precision

nefe/number-precision: 🚀1K tiny & fast lib for doing addition, subtraction, multiplication and division operations precisely

number-precision 是一个仅 1k 大小的 JavaScript 库（支持 TypeScript 类型），专注于精确执行加减乘除等操作，避免 JavaScript 默认浮点计算所造成的精度误差。

使用示例（典型用法）：

import NP from 'number-precision';

NP.strip(0.09999999999999998); // → 0.1
NP.plus(0.1, 0.2);             // → 0.3（而不是 0.30000000000000004）
NP.minus(1.0, 0.9);            // → 0.1（而不是 0.09999999999999998）
NP.times(3, 0.3);              // → 0.9（而不是 0.8999999999999999）
NP.divide(1.21, 1.1);          // → 1.1（而不是 1.0999999999999999）
NP.round(0.105, 2);            // → 0.11（而不是 0.1）

非常适合 金额计算、科学计算、财务统计等对精度要求高但是不超过 JavaScript 最大安全数范围的场景，如果你有其他类似需求（比如任意精度、复杂舍入规则等），也可以考虑更强大的库如 big.js 或 decimal.js（它们能处理任意精度的十进制运算）。

number-precision 的局限性在于 JavaScript 安全数的最大表示范围是 2^53（正负9,007,199,254,740,991），如果超过这个范围则推荐使用更强大的 big.js。

Evil Charts

Evil Charts - Beautiful & Animated Charts是一个开源、即插即用的 React 图表组件，基于 Shadcn UI 的技术栈，非常适合熟悉 tailwind + Shadcn UI 的开发者。

作者表示：“在寻找图表组件、平滑动画以及数据动态可视化时，我发现可选项较少。因此，我决定自己搭建一套。”

总的来说，这套组件的风格非常小清新，各种图表都配合着动画效果，代码示例非常完善，即插即用绝无问题。

Penpal

penpal 使用基于 Promise 的方法改进 iframe、Web Worker 及窗口间的通信，相较于原生 postMessage 来说，更符合使用 Promise 的习惯。

推荐大家把这个工具加入到自己的前端开发工具箱中 😁

md

如果你想直接写 markdown 文档，同时可以查看到能够直接复制到微信公众号编辑器的效果，那么请看：

doocs/md: ✍ WeChat Markdown Editor | 一款高度简洁的微信 Markdown 编辑器：支持 Markdown 语法、自定义主题样式、内容管理、多图床、AI 助手等特性

左侧 markdown，右侧就是具有样式主题的公众号预览效果（内置主题，用户自选），此外还支持完善的图床上传和 AI 编辑、修改等功能。 其功能特性如下 ：

• 支持 Markdown 所有基础语法、数学公式
• 供对 Mermaid 图表的渲染和 GFM 警告块的支持
• 提供 PlantUML 渲染支持
• 丰富的代码块高亮主题，提升代码可读性
• 允许自定义主题色和 CSS 样式，灵活定制展示效果
• 提供多图上传功能，并可自定义配置图床
• 便捷的文件导入、导出功能，提升工作效率
• 内置本地内容管理功能，支持草稿自动保存
• 集成主流 AI 模型（如 DeepSeek、OpenAI、通义千问、腾讯混元、火山方舟 等等），辅助内容创作

最后

笔者会继续更新周刊内容，坚持做这件事。

非常期待读者的点赞和支持，或多或少我都能从中得到鼓励❤️

好了，今天的分享就先到这里，大家下周见~

内容总览

• Axios header authorization 设置
• iOS Safari 100vh 设置
• Zustand 保存主题和暗色模式
• TanStack Query 和 Toast 控制重试和通知
• TanStack Query 数据的有效期和缓存
• C 端 SPA 鉴权和渲染

Axios token 设置

Axios 和 JWT 机制结合时，在客户端可以通过以下两种方式设置请求头 Authorization：

1. 拦截器设置
2. 实例设置

首先拦截器设置：

const instance = axios.create();

instance.interceptors.request.use((config) => {
  config.headers["Authorization"] = "Bearer " + localStorage.getItem("token");
  return config;
});

其特点是动态性强，不怕 token 动态刷新，缺点是逻辑每次都走一遍，当然性能上几乎可以忽略。

其次是在 instance 上设置：

const instance = axios.create({
  baseURL: "/api",
  headers: {
    Authorization: "Bearer " + localStorage.getItem("token"),
  },
});

// 当 token 变化时，需要手动更新
instance.defaults.headers["Authorization"] = "Bearer " + newToken;

只在初始化时或手动更新时设置，避免每次请求都走一遍，仅需要再刷新的时候重新设置。

这对产品来说没有什么价值，但是对开发者的个人体感来说是有价值的。此前我都是使用拦截器，现在我更倾向通过实例来设置。

对比一下二者：

iOS Safari 100vh 设置

在 iOS Safari 浏览器中，100 vh 的行为和浏览器不一致。

/* 在桌面浏览器中 */
.full-height {
  height: 100vh; /* 总是等于视口高度 */
}

/* 在 iOS Safari 中 */
.full-height {
  height: 100vh; /* 包含了地址栏和工具栏的高度！ */
}

直接看图说话，左侧全屏展示时是常规 100 vh，右侧为常规操作时页面，其 100 vh 可能和开发者期望的高度不一致。

在滚动状态时甚至会隐藏地址栏，因此需要一个方案来实现兼容性更好的 100 vh 高度方案。

首先给出常见的方案总结：

当真的需要兼容 iOS Safari 的时候，我才遇到这个问题。这里直接一步到位，跳过前两个方案。接下来再暂时放弃第四个方案，dvh 等新的单位是 2022 年提出的，现在使用恐怕会遇到兼容性问题，不如直接使用方案 3：JS + CSS 定义 css 变量。

上 React 代码（谢谢 UJ）：

import { useEffect } from "react"

/**
 * 修复 iOS Safari 下 100vh 不准确的问题
 * 自动设置 CSS 变量 --app-vh
 * 使用 requestAnimationFrame 限流，避免频繁操作 DOM
 */
export function useDomReadyReCalc() {
  useEffect(() => {
    if (typeof window === "undefined" || typeof document === "undefined") return

    const docElm = document.documentElement

    // iOS 检测（含 iPad 桌面模式）
    const isIOS =
      /iPad|iPhone|iPod/.test(navigator.userAgent) ||
      (navigator.userAgent.includes("Mac") && "ontouchend" in document)

    let ticking = false

    const updateVh = () => {
      if (!ticking) {
        requestAnimationFrame(() => {
          const vh = window.innerHeight * 0.01
          docElm.style.setProperty("--app-vh", `${vh}px`)
          ticking = false
        })
        ticking = true
      }
    }

    const setInitVh = () => {
      const vh = window.innerHeight * 0.01
      docElm.style.setProperty("--app-init-vh", `${vh}px`)
    }

    // ---- 初始计算 ----
    setInitVh()
    updateVh()

    // ---- 监听 resize ----
    window.addEventListener("resize", updateVh)

    if (isIOS) {
      // iOS 特殊处理
      window.addEventListener("orientationchange", updateVh)
      if (window.visualViewport) {
        window.visualViewport.addEventListener("resize", updateVh)
      }
    }

    // 清理事件
    return () => {
      window.removeEventListener("resize", updateVh)
      if (isIOS) {
        window.removeEventListener("orientationchange", updateVh)
        if (window.visualViewport) {
          window.visualViewport.removeEventListener("resize", updateVh)
        }
      }
    }
  }, [])
}

接着，在 React App.tsx 顶层调用一次即可在 CSS 中使用 css 变量来获取准确的高度。

Zustand 使用细节

Zustand 在使用 store 中的嵌套属性时需要注意代码的写法，应该使用选择性订阅而不是订阅整个 store，订阅整个 store 会大大增加渲染次数。

export function useIsDarkMode() {
  // forSTORE
  const theme$_isDarkMode = useThemeStore((s) => s.theme$_isDarkMode);
  const theme$_appTheme = useThemeStore((s) => s.theme$_appTheme);
  // forSTORE

  const { isSysDarkMode } = useIsSysDarkMode();

  return {
    isDarkMode:
      // 看主题
      theme$_appTheme
        ? // 如果有选择过，就按 theme 走
          theme$_isDarkMode
        : // 不然按 sys 走
          isSysDarkMode,
  };
}

选择 store 中的某个字段时，应该使用选择性订阅的语法来确保 store 更新的影响范围最小。

TanStack Query 和 Toast

TanStack Query 可以在创建 queryClient 的时候对整个 client 做通用配置，其中有一个 retry 的点引起了群友的讨论。

请求在出错、超时的情况下添加重试机制是一种很好的实践。TanStack Query 在默认情况下 retry 次数是 3 次，总共请求四次，有时候我们不需要重试这么多次，并且重试的时候可能会触发 Axios 拦截器中响应的逻辑处理，从而连续弹出多次 Toast。

这里面有两个优化点，首先是 retry 重试机制。将 retry 设置为 false 仅在特殊场景下（产品特性）可选，大多数情况下我们会自定义重试次数。看代码：

retry: (failureCount, error) => {
  if (error.status === 404) return false
  return failureCount < 2
}

针对性 404 状态码不需要重试，针对重试次数来判断是否需要重试，从而设置重试次数。通过函数来控制重试机制，灵活性大大提升，我们可以在这里做更多的逻辑处理工作，例如 Toast 提示。

此前，笔者尝尝碰到在 Axios 拦截器中写 Toast 的业务需求，于是笔者在群里提出了自己的解决方案：通过请求 url、query params、body 进行序列化处理成唯一的 key 来区分请求，利用防抖机制防止快速或重复的 Toast。

这种方案大伙觉得麻烦，Bruce 提出给 Toast 配置 maxCount 为 1，这样多次重试可以保证页面仅单个 Toast 效果，看起来不会像连续多次 Toast 那样差劲。

但是笔者觉得这样会有问题，同时发生的若干接口可能会需要展示若干个 Toast 内容，限制最大数量将会隐藏先触发的 Toast，如果产品团队不能接受这一点，那么我们就得换一个方案。

最后，提出问题的老徐直接建议我们把逻辑放在 retry 函数中来处理，直接把话题给终结了。

挺好，在 retry 中针对次数来决定是否需要 Toast，既防止连续相同的 Toast 效果不好，也隔离了不同的请求的 Toast 影响，不需要担心多个请求异常的 Toast 展示遗漏，也不需要处理复杂的请求唯一性检查 🚀。

TanStack Query 数据有效期和缓存

TanStack Query 能够将请求进行缓存，从而减少服务器压力，也能在特殊场景下快速响应数据，减少白屏。

来吧直接说场景：表格翻页渲染，我们希望给用户最佳的翻页体验和快速响应。

其中有两个关键的配置如下：

• gcTime 数据缓存时间
• staleTime 数据有效时间

在表格翻页的时候，如果希望能够立即使用缓存的数据作为响应立即展示，并且同时请求 API 获取数据来更新缓存，那么可以参考如下代码：

// 默认 Query 选项
export const defaultQueryOptions = {
  staleTime: 1000, // 1s数据保鲜期
  gcTime: 10 * 1000,   // v5 中 cacheTime 改名为 gcTime
  retry: 2, // 忽略 toast 逻辑
  retryDelay: (attemptIndex: number) => Math.min(1000 * 2 ** attemptIndex, 30000),
  refetchOnWindowFocus: false,
  refetchOnReconnect: true,
};

// 创建 QueryClient 实例
export const createQueryClient = () => {
  return new QueryClient({
    defaultOptions: {
      queries: {
        ...defaultQueryOptions,
        throwOnError: false,
      },
      mutations: {
        retry: 1,
        throwOnError: false,
      },
    },
  });
};

接下来请求数据：

export const useUsers = (params: TableParams) => {
  const queryClient = useQueryClient();

  const query = useQuery({
    queryKey: userQueryKeys.list(params),
    queryFn: () => fetchUsers(params),
  });

如此一来，切换页面的时候如果在 1s 内，则走缓存数据并且不触发 API 请求。如果在 1s 后则立即渲染缓存数据，同时走 API 请求，拿到最新数据之后立即同步 UI 和更新缓存。

开发者可以自行选择 1s 的窗口时间，降低服务器压力。如果有需要我们甚至可以把 staleTime 改为 30s，并且使用 prefetchQuery 提前加载下一页、上一页的数据，从而让用户对分页的数据响应获得更快的体验。

预加载是平衡性能和体验很好的一种方案。

C 端 SPA 鉴权和渲染：数据优先，渲染在后

在 C 端，单论 SPA 的场景来说笔者的观点如下：

• 全局初始化优先于路由渲染
• Suspense + 动态组件加载的结合
• 鉴权逻辑非常重要

笔者认为在渲染路由之前，应该执行的是初始化的一些逻辑。

如若任何一个路由都使用 Suspense 和动态加载组件，那么路由在加载之前就应该读取应用的配置，并且初始化 Zustand 的 Store 数据，在初始化完成之前，都展示 Suspense 的 fallback 组件，这是一个全路由通用的组件，甚至可以加上一些品牌相关的 UI 和动画。

另外诸如多语言、主题和设置、CSS 变量、鉴权等都在渲染路由之前初始化，其他的暂时不说，直接说鉴权。

在渲染路由之前，首先得判断当前 token 有效性，这时候就可以通过异步逻辑去获取用户信息，从而确保应用启动之后拿到的是最新的用户信息。

如若直接在 login 的时候将信息和 token 保存到 localStorage，然后直接渲染路由，那么在 token 过期的时候就可能会导致多个组件先后请求自己的数据，并且引发 401 之后的多个逻辑。亦或是 userInfo、token 变更，将 localStorage 中的 userInfo 作为初始值也得处理信息变更的逻辑，否则用户的姓名甚至都可能变化了，UI 还展示旧的信息。

用户信息和 token 有什么必要保存到 localStorage 中呢？我想仅有的原因是用户的个人习惯是通过浏览器刷新功能来重新查看数据。如果真有这部分考量，那么确实应该保存到 localStorage，并且可以结合默认读取 localStorage，同时通过独立的鉴权请求去更新用户信息和 token。

通过 Zustand 初始化数据，那么组件就不需要再通过重复逻辑获取配置数据。其次，Suspense fallback 可以防止白屏和闪烁，也可以让动态加载的好处提现出来，初始 bundle 将会变得更小，每一个路由都拆分成独立的包，用户访问某个路由下才下载对应的代码。

渲染页面之前确保数据是存在的，组件内的代码也可以减少很多不存在的数据逻辑。

如果你也赞同笔者的想法，那么一定要看看这个库：TanStack Router

这个库简直是，啧啧啧。

无懈可击。

在 React 生态下提供完善的 TypeScript 支持、绝佳的路由定义（基于文件目录和配置）机制、独特的路由渲染前上下文控制、数据请求配置、Suspense 机制加持懒加载功能、完善的 URL 序列化和反序列化支持（代替 nuqs）等等。

堪称 Tanstack Query 的绝配。

最后

笔者考虑了很久，最终决定将本文作为付费内容进行发布，我希望自己生产的内容是有价值的，即使其价值很低（😞）。

另外，周刊的内容依然会免费更新，给大家带来自己接触到的新玩意。

Bye.

前言

我接触的第一个浏览器是 IE，随着上网经验的积累，IE 渐渐变成了用来下载 Chrome 的工具。在 2022 年以前，Chrome 始终是我最常用的浏览器。2022 年发生了什么？

2022 年，Arc 浏览器横空出世，产品团队以“重新想象浏览器”为 Slogan，为 Arc 赢得了大量忠实用户。

Arc 浏览器极具辨识度的左侧侧边栏、空间概念、垂直标签页和丰富的自定义能力，吸引了众多数字原住民和极客用户，口碑极佳！

然而，Arc 的创新也带来了使用门槛——对于许多习惯了 Chrome、Safari 传统布局的用户来说，Arc 的操作模式过于新颖，学习成本较高。根据官方数据，Arc 的核心特色功能（如多空间、Live Folders 等）实际使用率并不高，绝大多数用户并未充分利用这些“生产力利器”。

新的道路

2025 年，Arc 开发团队决定不再开发新功能，现有团队的主要精力已全面转向新一代 AI 浏览器 Dia。Arc 目前仅会继续进行安全补丁和必要的维护，不再进行功能性更新或大版本迭代。

团队认为，AI 驱动的浏览器才是未来的突破口，因此决定“推倒重来”，以 Dia 为新起点，打造更简洁、速度更快、AI 深度集成的新一代浏览器。

Dia 基于 Chromium 内核，界面风格更接近 Chrome，采用传统的水平标签页布局，并将 AI 助手原生集成到侧边栏与地址栏中。与 Arc 的“重塑浏览器交互”不同，Dia 更强调“让 AI 融入每一个上网动作”：用户可以随时向 AI 提问、总结当前标签页内容、跨标签比较信息，甚至通过“Skills”自定义一系列自动化操作（如写作辅助、代码生成、表单填充等）。

Dia 社区呼唤开发团队将 Arc 的优点集成到 Dia：垂直标签页、Spaces、快捷键自定义

Dia 的研发初衷是响应 AI 技术的爆发式普及和用户需求的转变。The Browser Company 的 CEO Josh Miller 直言，Arc 虽然获得了小众极客群体的热爱，却难以打动更广泛的主流用户。“我们发现，AI 聊天已经成为年轻用户的日常习惯。与其让用户不断切换到 ChatGPT，不如直接把 AI 深度融入浏览器，成为每一次上网的天然助手。”Dia 的“Skills”系统被比作 AI 时代的 App Store，未来有望根据场景自动调用不同的 AI 能力，甚至支持第三方开发者扩展。

在隐私与安全方面，Dia 宣称绝大多数数据本地加密存储，仅在调用 AI 服务时临时上传必要内容，且服务商不得保存或训练相关数据。这一“隐私优先”的策略，旨在化解用户对 AI 浏览器“过度采集数据”的担忧。

用户反馈

笔者在 reddit 上看到一篇 Dia 用户的文章和其他留言，传送门。

Dia 的极简设计、AI 原生集成、快速响应等特性获得了用户的认可，尤其是在内容写作、资料整理、学习辅助等场景下，AI 能够节省大量繁琐操作。

“我习惯在 Cursor 里用 AI 辅助编程，现在在 Dia 里也能边看网页边和 AI 深度对话，非常高效。”

但他们同样期待 Dia 尽快补齐标签页管理、空间分组等核心功能。（Dia 官方在社交媒体上回复用户，这部分功能将会在未来两周上线。）

另一个讨论热点是“收费模式”与“数据隐私”。不少用户担心，Dia 未来会不会像部分 AI 工具一样走高价订阅路线，或者对个人数据进行过度采集。官方目前的说法是：“基础浏览器免费，高阶 AI 功能可能付费”，但实际策略尚未完全明朗。

Dia 调查问卷：如果我们对使用Dia收费，那合理的价格是多少？

免费到底？不可能，AI 服务始终是资金堆起来的，最后大概率是订阅的价格拉扯问题罢了。

对于普通用户而言，Dia 的极简设计和 AI 辅助能带来一定便利，适合日常轻量办公、内容消费和简单自动化场景；对于重度生产力用户，当前版本的功能还远未达到 Arc 的高度，建议观望后续迭代。

如果你对 AI 驱动的浏览器体验充满好奇，愿意尝试新工具，并且对标签页管理等高级需求不那么刚性，可以申请试用 Dia，感受“AI+浏览器”带来的新体验。但如果你已经习惯了 Arc 的垂直标签、空间分组、深度自定义等特性，Dia 当前还不足以成为完全替代方案。未来，随着功能补齐和生态完善，Dia 能否真正成为“AI 时代的主力浏览器”，仍有待市场和用户的进一步检验。

我的使用体会

前段时间我下载了 Dia，最近办公也在高频使用 Dia 浏览器，个人非常喜欢 Dia 的 UI 和交互。

让我印象深刻的功能有：

• 浏览器可以执行脚本，用户可以通过自然语言和浏览器 AI 交互，例如：我最近七天看了哪些 YouTube 链接的视频？AI 能够从历史记录中分析数据并反馈结果
• 随处可 Chat with AI！任选内容和页面就可以通过快捷键唤起 AI Chat 功能
• 浏览器级别的窗口拆分，像 terminal 一样可以左右分屏，且完全是独立窗口而非 Iframe，这一点是插件无法实现的，我一直对此非常遗憾
• 新建标签页设计得非常好，可以通过交互轻松切换 Chat 模式和搜索模式，输入内容的智能推测也很出色
• UI 非常干净，极简风格让我耳目一新，细节打磨得非常好，例如 URL 不仅仅是 URL，也包含页面的 Title 等等信息
• 自定义命令支持：创建自定义命令，可以让 AI 帮你完成一些事情。用户只需要在 Chat 的时候输入 ‎⁠/command⁠ 就可以快速通过预置的 prompt 进行交互
• 网络搜索+AI 能力融合，检索信息非常方便
• 直接在地址栏或侧边栏输入问题，AI 可基于当前网页进行内容总结、对比、写作、代码生成等
• 用户可用自然语言描述需求，让 AI 帮你创建“Skills”——比如一键切换阅读模式、自动填写表单、批量整理标签页等
• 在任意文本框内，AI 可充当写作助手，帮你润色、改写、翻译、生成摘要，甚至模仿你的写作风格

但也存在一些问题：

• 浏览器插件的 Side Panel 不可用，估计是开发团队将 Side Panel 彻底改为了核心的 AI Chat 功能
• 无法保留上次打开的页面，当浏览器退出之后页面将会全部关闭，仅能从历史记录中逐个打开，非常不方便。但好消息是，官方在社媒上回复用户这个功能将会很快支持。

最后

嘿嘿，最后在这里分享一下我的邀请码，官方限制仅可邀请三人，先到先得：

https://diabrowser.com/invite/T0DD8A

啊，对了！windows 用户暂时没法用 Dia...

最后，欢迎各位点赞和转发支持！Bye！

场景

我们有一个后台系统，产品经理提出一个需求：在当前系统内部调用另一个系统的一些服务。

两个系统之间的代码虽然可以通用，但之前并没有做 Monorepo 之类的规划，因此我们决定通过 iframe 引入另一个系统的服务。

实现

细节方面不再赘述 🤣

在常规引入 iframe 之前，我对目标项目做了修改，新增了一个无鉴权的路由，通过 URL 接收当前系统传来的基础数据和鉴权 token，然后用 token 换取目标系统的 JWT 数据，再重定向到最终的路由。

问题不断出现

整个流程非常简单，直到今天测试同事找到我说页面打开报错了。

起因很简单，后端提供了一个超大的 JSON 数据，我编码后通过 URL 传递给目标系统的 Next.js 服务进行处理，导致 Next.js 返回了 431 状态码（Request Header Fields Too Large）。这可能是 URL 过长导致的问题。

我首先想到，JSON 数据序列化为字符串后，经 encodeURIComponent() 编码可能过长。此前数据序列化后长度正常。

encodeURIComponent() 编码可确保 URL 格式合法，防止查询分隔符破坏结构，处理非 ASCII 字符，并提升跨平台兼容性。

于是我灵光一闪，想到此前处理过一个场景：通过 btoa() 将字符串转为 Base64 字符串，其长度通常比 encodeURIComponent() 编码的结果短。于是，我尝试通过 Base64 编码超大数据并传递。

btoa()（"binary to ASCII"）是浏览器提供的内置方法，用于将二进制字符串编码为 Base64。

可惜我忽略了一点：btoa() 方法仅支持 Latin1 范围内的字符，无法处理中文、emoji 或特殊符号。

结果我犯蠢了，很显然：Base64 编码后字符串很长，甚至比 encodeURIComponent() 处理后更长。

于是我立即引入了 pieroxy/lz-string 库来压缩 Base64 字符串！

pieroxy/lz-string: LZ-based compression algorithm for JavaScript：压缩 Base64 字符串的利器，常用于 localStorage 存储或将图片解压为 Base64 嵌入 HTML 等场景。

🚀 不错，Base64 字符串压缩后变小了，lz-string 还能自动处理 Latin1 范围外的字符，省心省力！

但是...

Base64 字符串可能包含 URL 中的分隔字符。为确保数据完整性，仍需通过 encodeURIComponent() 进行编码。

通过 URL 传输超大 JSON 数据就像一条岔路，也许我们一开始就不应选择这种方式。

RESTful API 规范建议开发者通过 GET 请求 API 接口，通常通过 URL 传递参数实现，但不适合数据量大的场景。浏览器、后端、网关等都可能破坏 URL 中数据的完整性。

换一条路

通过 Channel Messaging API 机制，在父窗口和 iframe 之间建立安全的双向通信信道。

如果你想了解原生 Channel Messaging API 的通信机制，可查看 Channel Messaging API - Web APIs | MDN。

如果是一年前，我可能会自己封装代码实现所需功能，打造一把“锤子”。

但现在，我直接使用了 Aaronius/penpal 库，它基于 postMessage 提供简化的通信功能。

让我们花几分钟看看示例，在父窗口创建 iframe 和 messenger 实例来连接子窗口：

import { WindowMessenger, connect } from 'penpal';

const iframe = document.createElement('iframe');
iframe.src = 'https://childorigin.example.com/path/to/iframe.html';
document.body.appendChild(iframe);

const messenger = new WindowMessenger({
  remoteWindow: iframe.contentWindow,
  // Defaults to the current origin.
  allowedOrigins: ['https://childorigin.example.com'],
  // Alternatively,
  // allowedOrigins: [new URL(iframe.src).origin]
});

const connection = connect({
  messenger,
  // Methods the parent window is exposing to the iframe window.
  methods: {
    add(num1, num2) {
      return num1 + num2;
    },
  },
});

const remote = await connection.promise;
// Calling a remote method will always return a promise.
const multiplicationResult = await remote.multiply(2, 6);
console.log(multiplicationResult); // 12
const divisionResult = await remote.divide(12, 4);
console.log(divisionResult); // 3

在子窗口也创建 messenger 来连接父窗口：

import { WindowMessenger, connect } from 'penpal';

const messenger = new WindowMessenger({
  remoteWindow: window.parent,
  // Defaults to the current origin.
  allowedOrigins: ['https://parentorigin.example.com'],
});

const connection = connect({
  messenger,
  // Methods the iframe window is exposing to the parent window.
  methods: {
    multiply(num1, num2) {
      return num1 * num2;
    },
    divide(num1, num2) {
      // Return a promise if asynchronous processing is needed.
      return new Promise((resolve) => {
        setTimeout(() => {
          resolve(num1 / num2);
        }, 1000);
      });
    },
  },
});

const remote = await connection.promise;
// Calling a remote method will always return a promise.
const additionResult = await remote.add(2, 6);
console.log(additionResult); // 8

配置明确的 allowedOrigins 后，消息传递具有较高的安全性。

此外，penpal 还适用于 Web Worker 之间的通信，尤其适合超大数据传输，能节省大量时间以专注于更有意义的工作。

注意：任何时候都可通过调用 connection.destroy() 销毁连接，以移除事件监听器并正确进行垃圾回收。

最后

准备下班，经验总是在不经意间积累起来的，下次再见。

当然，期待大家都点赞、转发和支持！

Exploring JavaScript ES2025

著名工程师 Dr.Axel 发布了最新版的免费电子书《Exploring JavaScript ES2025》，作者自述：****“探索 JavaScript” 通过提供尽可能一致的现代视角，使得该语言对新手来说更加容易学习。

无论你是新手小白，还是一个资深的 JavaScript 开发者，这本书都可以让你了解到最新的 JavaScript 知识，以及作者分享的部分****测试驱动的编程练习，最重要的是：免费！

你可以免费阅读在线版：Table of contents • Exploring JavaScript (ES2025 Edition)

Shopify 团队推动浏览器 Import Maps 支持

Shopify 团队积极适配了现代浏览器的 Import Maps 支持。文章提到，Import Maps 在 Chrome（版本 133 起）和 Safari（版本 18.4 起）等浏览器中可用。他们通过 Polyfills 或其他兼容性方案，确保在不支持 Import Maps 的旧版浏览器中仍能正常运行。

Import Maps 是浏览器原生支持的一种 JavaScript 功能，用于控制和映射 ECMAScript 模块（ESM）的导入路径。它通过一个 JSON 格式的配置（通常嵌入在 HTML 的