随着 Vibe Coding 实践越来越多，越来越顺手，效率提高了不少。但有些选择，还是琢磨了很久：

• 长会话还是短会话？
• 代码出问题，推翻重写还是让它改？
• Plan 模式还是 Agent 模式？
• 用 Git 管理还是用工具自带的功能？
• 用最强模型还是最快模型？

和周围 Vibe Coding 的朋友聊过，发现大家也有类似的琢磨。这篇就聊聊这 5 个选择，不一定对，权当一个探索中的讨论。

1. 长会话 vs 短会话

长会话：一个任务从头到尾在一个对话里完成。交代背景、提需求、写代码、发现问题、继续改，一路聊下去。

短会话：任务拆成小块，每块开一个新对话。每次对话只做一件小事，做完就开新的。

在琢磨什么？

核心问题是上下文。

长会话的好处是 AI 知道你之前说过什么。你说”把刚才那个函数改一下”，它知道你在说哪个函数，不用每次都解释一遍背景。

但长会话有两个坑：

第一个是上下文”污染”。聊着聊着，之前的错误尝试、被否定的方案、临时的 debug 代码，全都还在 AI 的记忆里。它可能会被这些东西影响，做出奇怪的选择。

第二个是信息丢失。现在各大产品在上下文变长之后，都会采取压缩或总结之类的策略。这会导致一些信息丢失——而且这些策略目前不太透明，不是一个完全可控的状态。你不知道它什么时候压缩了，压缩掉了什么。

短会话的好处是每次都”干净”，没有历史包袱。但代价是你得自己维护全局视角，每次开新对话都要交代背景。

我的选择

我现在偏向短会话，会控制上下文用量不超过 70%。当然，有时候偷懒了也会直接聊下去。这块还在摸索。

还没想清楚的地方

什么时候算”上下文污染”了？有没有一个明确的信号？

有时候 AI 开始说一些奇怪的话，但你也不确定是上下文污染，还是它本来就没理解你的意图。

2. 推翻重写 vs 修改代码

推翻重写：完全回滚到某个状态，让 AI 重新生成代码。”这条路走不通，换一条。”

修改代码：基于当前状态，让 AI 继续修改。”这条路有坑，但我们能绕过去。”

具体来说，”推翻重写”我一般会做两种操作：

1. 回退：直接回到之前的某个版本
2. 清除 + 重开：拒绝变更，或者用 Git 清除未暂存的代码，然后重新开一个会话，重新沟通需求

在琢磨什么？

两个典型的场景：

合并冲突类：你用 worktree 并行开发了两个功能，合并的时候冲突了一片。代码逻辑可能没问题，但版本状态乱了。

实现逻辑类：AI 写的代码能跑，但实现方式不对。或者写着写着，方向歪了，做成了另一个东西。

我的选择

我以前其实很少推翻重写，基本都是让 AI 在原基础上改。

但现在不一样了。自从用了 Spec 驱动的方式之后，推翻重写变多了。因为有了规格文档，重写的成本变低了——AI 不用从零开始猜你要什么，它可以直接看文档。推翻重写不再意味着”从头再来”，而是”换一条路再试”。

还没想清楚的地方

改了几轮算”该止损了”？

有时候 AI 改了两三轮还没改对，你会纠结：是再给它一次机会，还是直接回滚重来？

3. Plan vs Agent

Plan 模式：AI 先输出一个计划/方案，你确认之后它再执行。”让我想想怎么做 → 好，开始做”。

Agent 模式：AI 直接开始写代码、调用工具。”边做边想”。

在琢磨什么？

Plan 模式让你在执行前有机会纠正方向，但多了一个步骤。Agent 模式效率高，但你得等到代码出来才能判断方向对不对。

还有一个问题：如何识别”复杂”的边界在哪？

我以前被灌输的观点是”复杂任务才用 Plan”。但问题是，有时候你觉得简单的任务，做着做着就变复杂了。

我的心路历程

说实话，我之前基本都是用 Agent 模式。

为什么？因为 Agent 快啊。你说一句话，它直接开始干活，几秒钟就能看到代码。Plan 模式呢？它还要先想一想、输出一个计划，你得看一眼再让它执行。感觉多了一步，有点”浪费时间”。

而且当时我对 Plan 的理解是：这是给复杂任务准备的。简单的事情，直接 Agent 不就行了吗？何必多此一举。

但问题来了——什么叫”复杂”？

我发现这个边界特别难判断。有时候你觉得挺简单的任务，做着做着就变复杂了。等你意识到应该用 Plan 的时候，Agent 已经写了一堆代码，方向还歪了。

转变

后来有一天我突然想通了一件事：Plan 模式的”成本”到底是什么？

无非就是多花几秒钟生成一个计划。

那这几秒钟，我真的在乎吗？

以前我在乎，因为我只能串行工作——等 AI 输出的时候我就干等着。但现在不一样了，我在逐步提升自己并行工作的能力。Plan 生成的那几秒钟，我可以看看别的任务、回复个消息。这个时间成本，突然就不存在了。

那既然时间成本没了，Plan 还有什么坏处吗？

想了想，没有。

• Plan 不会让结果变差。最坏情况下，它和 Agent 一样，只是多花了点时间生成计划。
• Plan 可能让结果变好。它会在执行前帮你理清思路，提前发现方向偏差。

既然没有坏处、可能有好处，那为什么不默认用 Plan 呢？

我的选择

所以我现在的做法是：Plan 是默认，Agent 是辅助。

大概的分配是：80% 的任务我都用 Plan 模式，只有一些很小很确定的事情（比如”给这个函数加个注释”）才直接用 Agent。

接着上面”推翻重写”那个话题说——用 Plan 模式，走偏的概率会降低。因为在执行前你就能看到它打算怎么做，偏了可以直接调整，不用等到代码写完才发现不对。

另外，如果你用了 Spec 驱动的方式（比如先写好需求文档、设计文档），再配合 Plan 模式，回滚重新执行会变得更可控、成本更低。因为 AI 有文档可以参考，重新生成的一致性更高。

如果你和我以前一样，觉得 Plan 模式”太慢”或者”只有复杂任务才用”，可以试试把它当成默认选项。你可能会发现，它对你没有任何负面影响，反而可能帮你少走弯路。

4. Git vs 工具自带

Git：用 git 命令或 GUI 工具管理 AI 生成的代码。git diff、git checkout、git stash、git reset 这些。

工具自带：用 AI IDE 提供的功能。比如采纳/拒绝按钮、回滚功能。

在琢磨什么？

核心是粒度和管理维度的问题。

• 工具自带提供的是块级别的采纳——你可以在一个文件里选择接受这一段、拒绝那一段。
• Git 基础功能更多是文件级别的——git checkout 一个文件，整个文件就恢复了。当然 Git 也能做到更细的粒度，但需要一些特殊技巧，比如 git add -p 或者用 GUI 工具手动选行。

还有一个区别是管理维度：

• 工具自带可以从会话级别来管理代码变动——这一轮对话 AI 改了什么，你可以整体采纳或拒绝。
• Git 没有”会话”的概念，它只知道文件变了，不知道这些变化是哪次对话产生的。

我的选择

我现在很少用工具自带的功能，基本都用 Git。

首先混用会带来混乱。Git 处理的是底层文件变更，工具自带处理的可能是 IDE 层面的状态，两者不一定同步。如果混用，最后会很难追踪：哪些改动被采纳了，哪些没有？

所以我需要 选一个，坚持用（至少作为主力）。目前对我来说，Git 的确定性更高。

还没想清楚的地方

有没有一种方式，既能享受工具自带的块级采纳的便捷，又不会和 Git 状态冲突？

5. 最高性能 vs 最快速度

最高性能：选能力最强的模型。质量优先，愿意等。例如 Claude Opus、GPT-4o。

最快速度：选响应最快的模型。速度优先，能接受质量损失。例如 Claude Haiku、Gemini Flash。

在琢磨什么？

简单任务用顶级模型是不是浪费？复杂任务用快速模型会不会翻车？

我的心路历程

我之前的做法是：用性能最好的模型打地基。

为什么？因为地基很重要，框架质量不高的话，后面修补成本会很大。

但问题来了——后续遇到一些困难的问题，我还是不太放心交给速度优先的模型，最后还是会选性能好的。这样一来，最终其实没有拆分模型，大部分工作还是用的顶配。

后来我开始尝试一个新思路：先用有性价比的模型打地基，遇到疑难问题再用最好的模型。

为什么这个思路可能可行了？因为我有详细的 Spec 文档。AI 不用猜我要什么，它可以直接看文档，而现在”普通”模型在纯执行层的能力基本可靠，所以这种情况下打地基问题也不大。只有遇到真正复杂的问题（比如一些诡异的 bug、需要深度推理的逻辑），再切到最强模型。

还没想清楚的地方

这里有一个核心难题：怎么判断一个任务该用什么模型？

用好模型做地基，后面修补是不是也得用好模型？遇到小 bug，用好模型去修感觉大材小用，但用普通模型又不一定能修好。

说实话，这个判断挺难的。不同模型的局限和特长，需要自己慢慢摸索。所以更好的方式，是让工具自动帮你选模型。

现在很多 AI 编程工具都有这类功能，比如 Cursor 的 Auto 模式、Claude Code 的模型切换等。它们会根据任务复杂度、类型自动选择合适的模型——简单任务用快的，复杂任务用强的。这样既不用自己纠结，也能在保证效果的前提下提升效率、降低成本。

如果你也有类似的纠结，可以试试这类自动选择模型的功能。

写在最后

这 5 个小岔路口，没有标准答案。

我分享的也不是什么最佳实践，只是我的一些想法和尝试。你的答案可能和我完全不一样，这很正常。

不过有一点我觉得非常正确：Vibe Coding 看起来上手简单，但真要用好，还是需要刻意去练的。

就像我们当年学过设计模式、架构思维、各种技术方案一样，它不是一个天然就会的东西。都需要在工作中刻意积累、刻意练习。用得好和用得一般，工作效率差距挺大的。

这 5 个选择只是我琢磨过的一部分，肯定还有很多我没想到的。如果你也有类似的”琢磨”，或者有不同的选择，欢迎在评论区聊聊——

• 你试过 Plan 模式吗？是默认用还是只在复杂任务时用？
• 你有没有发现某个模型特别适合某类任务？
• 你更倾向长会话还是短会话？有没有自己的一套判断标准？
• 代码出问题到什么程度，你倾向于直接推翻重写？

毕竟 Vibe Coding 这件事，大家都还在摸索，多交流说不定能少踩点坑。

尤记得上半年大家对 MCP 的狂热，遇人就会和我聊到 MCP。然而从落地使用上似乎不是这么个情况。社区里面流传着一句话：MCP 是一个开发者远超使用者的功能。那么 MCP 真的是世上最大骗局吗？

如果你是 AI 工具的用户（而不是开发者），这篇文章可能会从另一角度来尝试解释：为什么 MCP 这么火，但你用起来总觉得”没什么用”？Skills 为什么可能才是你真正需要的东西。

一、MCP：开发者的狂欢，用户的懵圈

MCP（Model Context Protocol）在 2024 年底由 Anthropic 发布，号称是 AI 领域的”USB-C”——一个标准化的协议，让 AI 可以连接各种外部工具。

听起来很美好。但现实是社区里充斥着对 MCP 的嘲讽，称其为”最大骗局”。

MCP 可能是唯一开发者比使用者还多的技术
开发者为什么吐槽 MCP 协议？

这意味着什么？

大量开发者在「研究」MCP，但真正能给用户用的工具少得可怜。

SDK 月下载量 9700 万次，Registry 增长 407%——开发者热情高涨。但作为用户，你打开 Claude 或 Cursor，想找个好用的 MCP 工具，大概率还是会失望。

这不是 MCP 的错。这是它的「基因」决定的。

二、协议的「基因」决定了谁受益

为什么 MCP 对用户不友好？也许答案藏在协议设计本身。

我们对比下 MCP 和 Skills（Agent Skills）两个协议的规范：

来源：modelcontextprotocol.io / agentskills.io

MCP 协议规定的是「开发者怎么写工具」——API 接口怎么定义、数据结构怎么传递、SDK 怎么集成。这些对开发者很重要，但普通用户根本不关心。

Skills 协议规定的是「AI 怎么用能力」——什么时候加载、怎么理解指令、如何执行任务。这些直接影响用户体验。

即使开发者来说，Skill 的上手成本也都远低于 MCP。甚至简单的 Skills，使用者可以在使用过程中无缝切换为开发者，边用边优化。

一句话总结：MCP 面向开发者，尽力优化了开发体验，在 Agent 如何使用这些工具上却没有给出太多指导；Skill 面向使用者，优化使用体验（包括成本），在 Agent 如何使用这些工具上给出了很多指导。

协议的设计目标，决定了谁能从中获益。

三、Skills 的杀手锏：渐进式披露

除了设计目标不同，Skills 还有一个技术上的优势：渐进式披露（Progressive Disclosure）。

这是什么意思？用一个类比来解释：图书馆找书。

想象你去图书馆找资料：

MCP 方式：管理员把整个书架的书全搬到你面前。结果：信息过载，找不到重点 📚📚📚

Skill 方式：管理员先给你一本目录，你说要哪本再拿哪本。结果：精准高效 📋→📖

AI 的「脑容量」有限（Context Window）。

• 传统方式：一次性加载所有工具定义。假设有 100 个工具，可能占用几十万 tokens。
• Skill 方式：启动时只加载名称和描述（约 100 tokens/skill）。需要哪个，再加载哪个的详细指令。

根据 agentskills.io 官方规范：

• 元数据层：~100 tokens/skill
• 完整指令：建议 %&-l-t%5000 tokens

这意味着什么？100 个 Skills，启动时只需要约 10,000 tokens 的元数据。而不是一股脑塞进去几十万 tokens。

1. AI 不会被无关信息干扰，更聪明
2. 响应更快
3. 能支持更多工具

四、两者不是对手，是搭档

说了这么多 Skills 的好话，是不是意味着 MCP 没用了？不是。

MCP 和 Skills 解决的是不同层次的问题：

• MCP = 工具箱：定义了「能连接什么」——数据库、API、文件系统、第三方服务
• Skills = 使用手册：定义了「怎么聪明地用这些工具」——工作流程、最佳实践、按需加载

它们也可以结合使用：

用 Skills 的渐进式披露来管理 MCP 工具。

MCP 负责「连接」，Skills 负责「智慧」。组合是一个好的解决方案。

五、给用户的建议

1. 别光被 MCP 的热度带节奏。22000+ 个仓库听起来很多，但落地的有多少呢？
2. 关注 Skills 生态。如果你用 Claude Code 等工具（近期 Kwaipilot 也会支持），Skills 可能比 MCP 更能直接提升你的体验。
3. 两者都关注。长期来看，MCP + Skills 的组合可能是一种选择。MCP 提供连接能力，Skills 提供使用智慧。
4. 2026 年：渐进式披露和动态上下文管理会成为 AI 工具的标配。近期我的一个实践 —— 基于 20w 字的 Specs 来让 Agent 实现一个 10pd 需求 —— 也是通过渐进式披露 Specs。Cursor 也已经给出了很好的解释。

结语

MCP 是最大骗局吗？不是。它也是一个优秀的开发者协议。

Skills 是救星吗？对用户来说，目前来说可能是的。

协议的设计目标，决定了谁能从中获益。 MCP 让开发者更容易写工具，Skills 让用户更容易用工具。

如果你是用户，别纠结 MCP 为什么”不好用”了。去看看 Skills 吧。

参考链接

• MCP 官方文档
• Agent Skills 官方规范
• Anthropic Skills 发布公告
• 开发者为什么吐槽 MCP 协议？

先放一个我目前的工作布局，可能和大家最大的区别是多了一个麦。

0. 先说一次「被迫真香」的经历

真正让我对语音输入改观的，不是在工位上，而是在车上。

有一次我在车上赶一个还没收尾的需求，类似「OAuth 登录这块流程要改一版」这种：

• 旧方案有历史包袱
• 新需求又不断加条件
• 中间还有埋点、埋坑、兼容性一大堆细节

问题在于，当时车已经在路上了：

• 会颠簸，我本来就有点晕车
• 姿势别扭，手伸出去一会儿就酸
• 光线、屏幕角度都不舒服

简单讲——这是一个对「打字」极不友好的环境。

但我不想浪费这段时间，于是只能再一次尝试使用语音输入进行 Vibe Coding：

• 先把当前需求的背景讲了一遍
• 又补了一堆之前踩过的坑和兼容考虑
• 中途不断自我推翻：「不对，这样做登录态会乱掉」「等等，那埋点就对不上了」

如果按照我过去对语音输入的印象，这一大段最后大概率会变成：

• 一堆识别错误的文字
• 一段需要我自己重整的烂帐

结果那次和 AI Agent 协作的表现有点超出预期：

• 它基本听懂了我在说什么
• 把那些犹犹豫豫的念头整理成了几个还算清晰的方案选项
• 顺手帮我列了一份「改版时要注意的坑」清单

我在那辆晃悠的车上，一边说一边看它的回应，突然有一种挺明显的感觉：

它不是在帮我「打字」，而是在帮我「想事情」。

那天结束的时候，我脑子里蹦出一个感觉：「这玩意儿，好像没我想的那么鸡肋。」

等车到地方，下车回到桌前，我又继续用起了语音，同时开始琢磨一件事：

如果在这么恶劣的打字环境下，语音 + AI 还能把这次需求整完，那是不是说明，我以前那套「语音没啥用」「不适合干正经活」的判断，本身就有点问题？

自那以后，我从偶尔用语音输入，到目前级高频使用（还为此升级了下设备），过去了一个多月。

这一个多月「语音」+「AI Coding」的实践让我的认知有了很大变化，这篇关于「语音输入」想来分享三件事：

• 我以前为什么觉得语音输入很鸡肋？
• 最近这波「真香」的底层变化到底在哪？
• 语音在 AI Coding 里适合干什么、不适合干什么？

1. 【成见】以前我为什么瞧不上语音输入

老实讲，我一开始对语音输入的直觉就两个字：鸡肋。

原因也不复杂，基本都是拿自己踩过的坑换来的结论。

1.1 识别不准带来的精神内耗

几年前我试过语音转文字：手机自带的、输入法里的，还有一些小众工具。体验大概都是：

• 说一句话，屏幕上出来一堆奇怪的字
• 专有名词基本全错：React、hook、useState、async/await 之类
• 标点乱飞，逻辑断成一节一节

然后我就得干一件很蠢的事：一边看着屏幕，一边拿回车和删除键当橡皮擦用，去改语音输出的内容。几轮下来，脑子里的结论就是：

修错误的时间 %&-g-t% 直接打字
修错误的情绪消耗 %&-g-t%%&-g-t% 打字

用几次就自然放弃了。

如果稍微理性一点看，过去的语音识别大概是这样的：

• 输出的是「字面文本」
• 只要错一个词，整句可能就变味了
• 完全不理解语义、不补全、不纠错
• 用户被迫「为机器说话」——刻意放慢、咬字清晰、尽量别说口语

1.2 说话这件事本身「不适合精确表达」

另外一个问题是：以前所有的语音输入工具，都在试图把「说话」当成「打字」的替代品。但我们日常说话，天然是这样的：

• 「那个…就是…那个弹窗…」
• 「不对，我刚刚说的那个逻辑有问题，应该是先 XX 再 XX」
• 「等等，这里应该还有一个边界条件」

而传统软件要的是：

• 精确的指令
• 结构化的输入
• 明确的参数

这俩一对比，问题就很明显了：语音天然是「模糊的」，但传统软件需要「精确的」输入。

所以以前的各种语音工具，为了对接上这些精确输入的软件，都在逼用户做一件反人类的事：

逼自己「像打字一样说话」。

结果就是，本来应该更轻松的语音输入，用起来反而比打字还累。

1.3 说错话的成本太高

最后一个很现实的小问题：撤回成本。

打字时，说错了就：

• Ctrl + Z
• Delete
• 光标回退，改两下

语音就不一样了：

• 你一旦说出口，整句都得重来
• 还要先停下来，等识别结果出来
• 发现不对，再去选中、删除、重说

有一说一，这种「一旦说出口就很难撤回」的感觉，会让人下意识紧张：「那我还是想好再说吧。」一旦进入「想好再说」这个模式，语音输入的速度优势基本也就没了。所以在很长一段时间里，我对语音输入的态度一直是：

在工作里顶多是个玩具，真要干活还是老老实实打字。

2. 【变化】最近这波变化，关键不在「听得更准」

那为什么这次我又真香了？直观感受上，最近这波变化有两个源头：

• 一个是技术本身确实进步了
• 另一个是「我们拿语音来干的事情」变了

这两个叠在一起，才让语音输入从「玩具」逐渐挪到了「主入口」的位置。以下这些都是我实际使用中观察到的，在 thinking 类模型上表现更佳。

2.1 技术这块：从「认字」到「懂你在说啥」

先看下技术面这几年到底进步了什么。

用一个简化版的对比表看一下：

单看这张表你会觉得，好像就是「更快更准」了，听上去不错，但似乎还没到「改变使用习惯」的程度。真正改变体验的是另一件事：语音识别后面，多了一层能理解上下文的「理解层」（例如你的下游软件是基于 LLM 的）。

为了方便直观一点，可以脑补成下面这张小图：左边是之前语音工具的链路，右边是现在配合 LLM 之后的链路：

这层「理解」插进来之后，有几个很关键的变化：

• 识别错几个字，不影响结果
• 说话可以口语化、断断续续，也能推出来主要意思
• 从「给精确指令」变成了「表达意图就行」

说白了，

以前语音输入的质量标准是「转录够不够准」，现在更像是「说说你的想法，AI 可以理解」。

2.2 LLM：把你的口水话整理成「可用信息」

刚才说的是「链路结构」的变化，再说点更偏体验的。现在的 AI 会把你那堆口水话当成有用的素材，而不是噪音。一个典型场景：

你对着麦克风说：「嗯……我想要一个函数……不对，应该是一个类……或者说，一个模块，能处理用户认证……」

过去很多系统：

• 会忠实地把这句话转成文本
• 然后把所有的「嗯」「不对」「或者说」也都塞进去

现在的 AI 更像是：「好的，他大概想要一个用户认证模块。」：

• 过滤掉大部分口水话
• 弄清楚你到底「最后倾向哪个方案」
• 同时记住你犹豫过的那几个选项（后面还可能有用）

这个时候，你的「思考过程」就不再是噪音，而是 AI 理解上下文的素材。所以有一个挺重要的视角切换：

语音输入的「输出质量」，不再取决于你说得有多完美，而是取决于后面那个理解你的模型有多能干。

2.3 对话上下文：语音可用性的隐形护栏

还有一条经常被忽略但特别关键的事：对话上下文。

想象一个很日常的情景：

你和同事已经讨论了 20 分钟技术方案，这时候你说：「那这个地方就按刚才说的那个方案来吧。」

你同事大概率事知道你在说什么，因为他有完整的上下文。

但如果一个路过的同时，临时加入你们，他会：

• 不知道「这个地方」是哪里
• 不知道「刚才的那个方案」是哪一个
• 甚至连你们讨论的具体功能都一头雾水

你和 AI 聊天，现在的特点是：

• 它不会「因为“上厕所”错过关键信息」
• 它不会「刚路过」才听到一半
• 它可以随时“回看”之前对话记录

这带来至少三类好处：

1. 语义消歧：

   • 你说错一个词，它可以根据上下文猜出你真正想说的
   • 比如你说成了「Ract」，但之前一直在聊 React 项目，它会自动当成 React

2. 专有名词识别：

   • 你之前提到过 useAuthStore，后面就算发音糊成一团，它也大概率能对上号

3. 思维连续性：

   • 「刚才说的那个方案」「那个弹窗」「前面那个接口」这种指代关系，它都能顺着上下文接回来

这也是为什么，在 AI 对话里说「那个」「刚才」「前面那个」比在传统软件里安全得多。

3. 【新生】换个视角看：语音到底在 AI Coding 里擅长什么

上面更多是在讲「为什么现在语音比以前顺手了」。

回到日常工作，我自己这一个多月下来，大概把语音输入在 AI Coding 里焕发出的新的用武之地，归成了这么几类。

3.1 和 AI「讨论」的时候，语音明显更顺

只要是下面这几类事，我现在基本都会先用语音输入：

• 需求还没完全想清楚，只是有一个大概的方向
• 想和 AI 一起推演几种方案的优劣
• 在排查复杂 Bug，需要把现象和怀疑点都说一遍

举个最近的一个真实场景。那阵子我在琢磨 Duet3.0 怎么搞一个「Agent 帮你 Review」的功能，脑子里有很多还没想清楚的问题：

• Agent 到底 review 什么？只看语法 / 代码味道，还是要看需求对齐？
• 人和 Agent 怎么分工？是 Agent 提建议，人拍板，还是 Agent 先改一版？
• 在实际 IDE 里，这个东西应该长成提示气泡、侧边栏，还是一个独立面板？

我一开始是打字和 AI 对话，想把这些问题讲清楚，结果发现特别费劲：「我在想一个 Agent Review 的功能，大概是 Agent 帮我看 PR，然后……」

敲了两段，感觉自己像在写 PRD，而不是在跟一个同事讨论想法。

后来我直接开语音，像在走廊上拉着同事聊一样说：「我最近在想一个事儿：现在大家都在做 Agent Review，但大部分产品巴拉巴拉……我更想要的是那种巴拉巴拉……那人和 Agent 的边界应该怎么划比较自然？是让它直接在 diff 里改，还是只给建议？还有一个问题是，Review 结果要放哪里比较不打断人——是像现在 IDE 的问题列表一样塞一堆 issue，还是更像一个‘和 reviewer 聊天’的侧边栏？」

这段话如果让我打字发，我肯定会自觉把很多犹豫、吐槽和半成型的想法删掉，只留下比较「正式」的版本。但语音的时候，我可以把这些真正在意的小勾小角都丢出来。

最后 AI 给我的反馈，也明显不是那种「看起来很正确但有点空」的 checklist，而是：

• 先帮我拆出来几条核心决策：Review 范围、人与 Agent 的分工、UI 呈现位置
• 根据我反复提到的「不要打断人」这点，给出了建议
• 结合我们已有的 Agent 能力体系，提醒我考虑 Review Agent 和其它 Agent 之间的接口设计

这个体验让我感受比较深：

在需要「讲故事」的场景里，语音比打字自然太多，而 AI 又刚好很吃「故事」。

3.2 头脑风暴、列想法的时候，语音很适合作「起手式」

还有一类场景，是我在写文档或设计方案的早期阶段：

• 只是想先把脑子里一堆零碎的点倒出来
• 不追求结构、条理、格式
• 甚至连结论都是模糊的

这时候用语音会变成一种很轻松的输出方式：「我现在脑子里大概有三个方向，第一个是把 XXX 做成一个独立服务，这样好处是 ABC，坏处是 DEF；第二个方向是…」

说完之后，我一般会让 AI 帮我做两件事：

1. 把这堆口水话整理成一个比较干净的大纲
2. 帮我标出它听到的「担心点」和「决策点」

然后我再回到键盘模式，开始填细节、改措辞。

如果全程打字，我会有很强烈的「写文档」的心理负担。但用语音先说一遍，更像是「口头和同事过一遍想法」，压力小很多。

3.3 精确改代码，老老实实用键盘就好

当然，也有一些场景，我现在语音：

• 精确修改某一行的变量名
• 对现有代码做很细致的重构

这种事情的特点是：我心里已经非常清楚要改什么，关键代码已经在脑子里浮现，就差腾一下。这时候语音+AI 反而会拖后腿：

• 我要先描述位置
• 再描述改动
• AI 再理解一次
• 然后再帮我生成一段严格的改动

往往还不如自己编码来得快、来得可控。

我现在的习惯可以简单概括成：

• 「想问题、聊需求、搞方案」 → 用语音
• 「精确改、收尾」 → 用键盘

两者混着用，体验会好很多。

3.4 用一个小矩阵粗暴划一下边界

为了把这种「适合语音 / 适合打字」的界线讲清楚一点，我后来给自己画了一个小矩阵，大概是这样：

4. 【原因】从 Input Method 到 Thought Interface

上面这些更多是从「使用体验」讲的。我也尝试思考了背后可能的原因，如果我要问我自己一个问题：

语音在这波 AI 浪潮里，究竟是个「输入法小功能」，还是一个「新入口形态」？

我自己现在的看法更偏后者。

4.1 两种心智模型的对比

用一个「白板一点」的画法对比传统输入法 (Input Method)和思维界面(Thought Interface)，大概就是：

核心差别其实就一句话：

传统输入法要的是「结果」，Thought Interface 不会忽视「过程」。

前者关心你最后敲出来什么字，后者关心你在想什么、怎么想的、犹豫过哪些选项。

4.2 信息带宽：可落地的、能逼近思维速率的输入方式

斯坦福大学 2016 年有个研究，测了下几种输入方式的速度（WPM）：

手机打字 : ████░░░░░░░░░░░░ 30 WPM
桌面打字 : █████░░░░░░░░░░░ 39 WPM
语音输入 : ████████████████ 165 WPM

• 语音比打字快 3～5 倍
• 而且短内容优势更明显：
  • 50 字以内：快 3.2 倍
  • 50-200 字：快 2.7 倍
  • 200 字以上：快 2.1 倍

在 AI 场景下，现在整条链路里最慢的那段真的是模型的输出速度么？可不可能是「人怎么把自己的意思说清楚」呢？

当你发现：

• 脑子里已经排好两三种方案，但打字的时候只能一条一条敲
• 想给 AI 讲清楚上下文，结果光组织语言就写了一页纸

那这时候提升「人 → AI」这段的带宽，就比继续优化「AI → 代码」更有价值。

语音目前是少数能明显放大这段带宽的手段。

4.3 认知负担：保持思维连续性

再从「脑子怎么运转」这个角度看一下。

差别在哪？

• 打字迫使你频繁从「思考模式」切换到「表达模式」
• 语音几乎不需要显式「切换模式」，嘴可以跟着脑子一起跑

在很多探索性很强的场景里（需求、方案、排查），这种「不断被打断」的感觉会非常明显——你会发现：

• 想问题的时候挺顺
• 一开始写，就容易卡在某一句话、某个词、某个结构上

语音在这里的优势不是神奇地「让你更聪明」，而是很朴素地：

少打断你。

4.4 信息含量：把思考过程也一并传过去

还有一个不那么显眼但很有意思的点，你说这句话的时候：「我想要一个函数……不对，应该是一个类……或者说，一个模块，能处理用户认证。」

实际上暴露了很多信息：

• 你最开始想的是「函数」这个粒度
• 然后意识到可能需要更重一点的抽象（类）
• 最后把它提升到「模块」的层级
• 说明你对这块的边界、职责是有纠结的

如果你直接打字，只写：「帮我创建一个用户认证模块。」那上面这些「犹豫」和「权衡」就全没了。

大家可能会觉得，这类信息没什么用；但对 AI 来说，这反而是很重要的信号：

• 它能理解你还有顾虑，可能会主动补上一些方案对比
• 它知道你不是要一个 Demo，而是一个真正能挂到系统里的模块

换句话说，

在有理解层的前提下，语音会天然传递更多「元信息」。

5. 【心得】什么时候用语音，什么时候老老实实打字？

讲了这么多，落到实操还是那两个问题：

• 语音到底适合用在哪些场景？
• 打字又在哪些场景更稳？

以下不是什么指南，只是我这一个多月边摸索边实践的心得体会。未来也会随着我使用的深入，继续迭代。

5.1 场景适配：哪里是语音输入的“甜点”

我目前的感受：

语音适合「开放/探索性」任务，打字适合「精准/确定性」任务。

5.2 混合用法：别给自己立「全语音」Flag

我自己现在比较稳的一套组合是（60%语音+40%键盘）：

1. 语音起手：
   • 跟 AI 讲清楚背景、目标、顾虑
   • 把脑子里的零碎想法先「倒出来」
2. AI 整理 + 大块实施：
   • 帮我归纳成结构化的大纲或方案，标出重点和需要决策的地方
   • 语音指挥 AI 开始大面积实施
3. 键盘收尾：
   • 精细修改措辞
   • 补充遗漏的细节

6. 【门槛】技术 OK 了，人（心理）还没准备好

技术问题解决了之后，剩下的基本都是心理问题。

6.1 「在工位说话会不会很尴尬」

一开始我也挺别扭的，第一次在开放工位对着屏幕说话，总感觉同事会用一种「你在干嘛」的眼神看我。但现实是：

大家真的没空管你。

绝大多数时候：

• 别人戴着耳机，压根听不见你在说什么
• 工位本来就有各种键盘声、椅子滑动声、讨论声，你那点语音根本淹没在环境噪音里

而且，现在大家早就习惯了视频会议、在线面试、远程沟通等各种「对着屏幕说话」的场景。你在工位小声跟 AI 说两句，别人顶多以为你在开会，很少有人会专门关注你。

6.2 「会不会吵到同事」

这个其实比想象中好解决：

• 麦克风离嘴近一点，小声说就行，现在的麦克风和识别模型对小音量非常友好
• 避开午休或者大家都很安静的时间段
• 实在不放心，就找一个会议室或茶水间试一阵，熟悉了再搬回工位

我现在的做法是：日常工位用一个还不错的麦克风，小声说话就能识别得很好。避开休息时间，工位上小声说话大家基本听不到。

说多了之后，心理门槛会肉眼可见地降低。

6.3 硬件小建议

我是在公司搞了个动圈麦，在家买了个电容麦：

• 动圈麦抗环境噪声比较好
• 电容麦灵敏度高，很小声地说，它也能听清
• 其实蓝牙耳机（比如 AirPods）也能用

总之，硬件这块也不用上来就搞设备，但如果搞麦克风，推荐搭配悬臂。

7. 【工具】如果想用语音，可以从哪里下手

这里简单列一些我自己试过的工具，用的种类不多，大家有更好的也可以分享：

7.1 AI Coding 产品里的语音支持

一般都有语音。之前用过，不少外国产品里中文上不咋行（尤其有的选简体中文后，还会出繁体）。如果你本来就在用这些工具，其实不需要额外上新软件，先试试，看看自己对语音输入的接纳度。

7.1 通用语音输入法

可以让你在 AI Coding 外的其他工具里也使用语音输入。

8. 【实操】如果你也想试试，可以从哪里开始

最后收个尾，给一份比较「落地」的起步建议。

8.1 先选一个你真会用起来的场景

别一上来就给自己立 Flag：「以后都用语音写代码」。基本会死在第一个小时。

比较容易成功的切入点有：

• 和 AI 讨论一个你还没想明白的需求
  • 用语音把疑惑、担心点全说出来
  • 不用管结构，先把自己脑子里的状态「dump」出来
• 排查一个难复现的 Bug
  • 把你看到的所有现象用语音描述一遍
  • 顺便把你怀疑过但被否掉的方向也讲给 AI 听

要是有一次体验到「原来这场景语音真的更省事」，后面就会很自然地多用一点，不需要强迫自己。我就是经历过两次放弃，又机缘巧合捡起来的。

8.2 接受「可以说得不完整」这件事

有个很重要的小心法：

把语音输入当成「思考过程的录音」，而不是「完美表达的工具」。

比如之前提到的，你完全可以这样说：「我现在有点乱，你帮我先记一下：第一点是 XXX，第二点是 YYY，第三点我还没想清楚，可能和 ZZZ 有关。你先帮我把前两点整理一下，顺便把第三点相关的问题列一下。」

说白了就是：

• 把「想清楚」的压力交给 AI
• 自己负责把脑子里的东西尽量完整地倒出来

我个人目前就是这个状态。这个心态一旦调整过来，语音输入会舒服很多。

8.3 混合使用语音 + 键盘，而不是二选一

前面已经说过一次组合拳，就不重复展开了，核心就是：

不要把语音和键盘当成互斥选项，而是当成一条流程里不同阶段的工具。

9. 【最后】补充一下

我现在也不会把语音输入吹成什么「生产力革命」，它绝对有自己的短板：

• 不太适合精确代码编辑（但我通过自己的一些实践，慢慢规避了）
• 不适合非常安静、对环境要求很高的办公场景（午休时候我就不语音了）
• 偶尔配上 LLM 识别还是会抽风（但真的很少，可能我说的比较长，密度虽低但架不住喷的多）

但对我个人来说，有一个变化挺真实：在需要「和 AI 好好聊一聊」的时候，甚至不知道该怎么组织思路开始的时候，我现在下意识会先点一下语音按钮，而不是直接开始打字。我所有的迷惑与混乱也都会发送给 AI，例如下面是最近我语音发给 AI 的一条消息：

可听化很重要。我可以把沉淀的东西放到 Tools 里整理起来，给一个目录，把几项功能都放一下。方案A，嗷不对，方案 B 可以吧？我不确定，可以试一试

识别有错词、语法不太通、方案选择也在摇摆。但无所谓，结果还是没跑偏。所以如果你最近也觉得：

• 打字跟不上脑子
• 和 AI 对话总是说不清楚背景
• 写方案的时候总是卡在「怎么开头」

那不妨给自己找一个15分钟的碎片时间，挑一个正在做的需求，开个语音，像和一个新人同事交接一样，把这件事「唠一遍」。

效果也许不完美，但如果你哪怕只体验到「好像有那么一点点更轻松了」，这件事就可能就值得继续试下去。

最近，在维护 KProxy（一个代理服务，Web 版的 charles） 时，遇到一个故障问题：一个请求的响应早已结束，但是在一段时间后却触发了 request timeout。

1. 问题描述

KProxy server 作为代理服务，收到用户请求时会向真实服务端（real server）发出的一个 HTTP 请求，实现代理。但是，在真实服务端响应结束之后（过了较长一段时间），这个 KProxy 中的该请求的 timeout 事件却被触发了。由于真实服务端的响应早已结束，预期是不会触发 KProxy 请求侧的超时的。结合 KProxy 这边的一些超时保障逻辑，就出现了误“封禁”的问题。

核心情况，简单来说就是：一个请求的响应早已结束，但是在一段时间后却触发了 request timeout。

2. 代码复现

KProxy 相关的完整代码比较多，下面重写了一份简版，用以复现问题。

server.js 是一个简单的服务端，监听 8088 端口，对于请求会响应一串”1”，2 秒后完成响应：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// file: server.js
const http = require('http');

http.createServer(function (req, res) {
    console.time('server-response-end');
    const timer = setInterval(() =%&-g-t% {
        res.write('1'.repeat(1e5));
    }, 20);

    setTimeout(() =%&-g-t% {
        clearInterval(timer);
        console.timeEnd('server-response-end');
        res.end();
    }, 2000);
}).listen(8088);

client.js 则会请求该服务：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// file: client.js
const http = require('http');

// 发送请求
const req = http.request({
    port: 8088,
    timeout: 5000,
}, res =%&-g-t% {
    // 一些省略的逻辑
});
req.end();
req.on('timeout', () =%&-g-t% console.log('request timeout!'));

// 每秒输出一下时间
let i = 0;
setInterval(() =%&-g-t% console.log(1e3 * ++i, 'ms passed'), 1e3);

启动 server.js，然后执行 client.js，会看到控制台输出以下内容：

可以看到，当时间来到第 5 秒时，timeout 事件触发了。而实际情况是，服务端在 2 秒的时候就已经调用 .end 方法结束响应了。

查看 TCP 连接情况，看到连接也一致没有销毁。

3. 如何修复

修复方式很简单，可以在回调里添加 res.on('data', () =%&-g-t% {}) 这样一行代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const http = require('http');

// 发送请求
const req = http.request({
    port: 8088,
    timeout: 5000,
}, res =%&-g-t% {
    // 一些省略的逻辑
+   res.on('data', () =%&-g-t% {});
});
req.end();
req.on('timeout', () =%&-g-t% console.log('request timeout!'));

// 每秒输出一下时间
let i = 0;
setInterval(() =%&-g-t% console.log(1e3 * ++i, 'ms passed'), 1e3);

看下输出结果：

不会再误触发 timeout 事件。连接也正常销毁了。

但这一段看似无意义的代码（监听了 data 事件但其实什么事情也没有做），是如何”修复“这个问题的呢？

4. 背后的原因

下面结合 Node.js v16.10.0 的源码，来解释一下这个问题产生的原因。

4.1. http.request 的大致实现

为了更好理解这个问题，先简单介绍一些和 http.request 相关的知识。

调用 http.request 实际会创建一个 http ClientRequest 对象。而 ClientRequest 类是继承自 OutgoingMessage 类的，它是一个 Stream。所以我们可以通过 Stream 的 API 向请求体中不断写入信息，并且通过调用 .end 方法表示请求写入完成，例如：

1
2
3
4
5

const http = require('http');
const req = http.request({ port: 8088 });
req.write('123');
req.write('456');
req.end();

请求体发送完毕后，下一阶段就是等待处理响应数据。在响应头处理完毕后，Node.js 会创建 IncomingMessage 对象，这个对象也是一个 Stream（准确来说是继承自 Readable Stream ）。然后调用 parser.onIncoming 方法：

1
2
3
4
5
6
7
8
9
10
11
12

function parserOnHeadersComplete(versionMajor, versionMinor, headers, method,
                                 url, statusCode, statusMessage, upgrade,
                                 shouldKeepAlive) {
  ...
  const ParserIncomingMessage = (socket && socket.server &&
                                 socket.server[kIncomingMessage]) ||
                                 IncomingMessage;

  const incoming = parser.incoming = new ParserIncomingMessage(socket);
  ...
  return parser.onIncoming(incoming, shouldKeepAlive);
}

对于 ClientRequest 来说，parser.onIncoming 实际就是 parserOnIncomingClient 方法，它会触发 response 事件：

1
2
3
4
5
6

function parserOnIncomingClient(res, shouldKeepAlive) {
  ...
  if (req.aborted || !req.emit('response', res))
    res._dump();
  ...
}

由于 ClientRequest 在创建时就会监听 response 事件来触发 http.request 的回调，因此在 http.request 的回调中或者 response 事件中都可以拿到 response 对象（IncomingMessage）。也就是说，回调触发的时候，响应头已经解析完毕，开始解析响应体。

涉及到的主要的类的大致关系如下：

所以如果想拿到响应体的信息，可以在回调里监听对应 data 事件。

1
2
3
4
5

const http = require('http');
const req = http.request({ port: 8088 }, res =%&-g-t% {
    res.on('data', (chunk) =%&-g-t% console.log(chunk));
});
req.end();

4.2. Request Timeout 的实现

http.request 在超时的实现上，并没有什么非常特别之外，就是通过 JS Timer 来设置一个定时器：如果到期未被清理，则会触发 timeout 事件。设置定时器最后会调用到 stream_base_common.js 中的 setStreamTimeout 方法：

1
2
3
4
5
6
7
8
9
10

function setStreamTimeout(msecs, callback) {
  ...
  if (msecs === 0) {
    ...
  } else {
    this[kTimeout] = setUnrefTimeout(this._onTimeout.bind(this), msecs);
    ...
  }
  return this;
}

this._onTimeout 则会触发 timeout 事件。

而我们更关注的是定期器的清除。因为请求超时的误触发，很可能会和没有成功清理定时器有关。那么，定时器何时会被清除呢？

当 socket 销毁时，定时器就会被清除：

1
2
3
4
5
6
7
8

Socket.prototype._destroy = function(exception, cb) {
  debug('destroy');
  ...
  for (let s = this; s !== null; s = s._parent) {
    clearTimeout(s[kTimeout]);
  }
  ...
};

对此，我们可以添加 NODE_DEBUG 环境变量来查看调试信息，使用下面命令启动我们修复后的代码（添加 data 空监听函数的）：

1

NODE_DEBUG=net node request.js 2%&-g-t%&1 %&-g-t%/dev/null | grep 'ms\|destroy'

可以看到，正常调用了 Socket.prototype._destroy 方法。

去掉 res.on('data', () =%&-g-t% {}) 这行修复代码再试一下：

可以看到，一直都不会触发 destroy。

4.3. IncomingMessage 与 Socket

定时器清除的逻辑和 Socket 对象相关，但我们的修复代码操作的是 IncomingMessage 对象，那么他们之间有什么关系呢？

Socket 类继承自 Duplex（读写流），在流结束后会调用上面的 Socket.prototype._destroy 方法。

在实际接收响应时，C++ 层的 node_http_parser

1
2
3
4
5
6
7
8
9
10
11
12

int on_body(const char* at, size_t length) {
  EscapableHandleScope scope(env()-%&-g-t%isolate());

  Local%&-l-t%Object%&-g-t% obj = object();
  Local%&-l-t%Value%&-g-t% cb = obj-%&-g-t%Get(env()-%&-g-t%context(), kOnBody).ToLocalChecked();

  ...
  MaybeLocal%&-l-t%Value%&-g-t% r = MakeCallback(cb.As%&-l-t%Function%&-g-t%(),
                                       arraysize(argv),
                                       argv);
  ...
}

会把解析的响应体内容传到 JS 层的方法里，最终调用 parserOnBody 方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

function parserOnBody(b, start, len) {
  const stream = this.incoming;

  // If the stream has already been removed, then drop it.
  if (stream === null)
    return;

  // Pretend this was the result of a stream._read call.
  if (len %&-g-t% 0 && !stream._dumped) {
    const slice = b.slice(start, start + len);
    const ret = stream.push(slice);
    if (!ret)
      readStop(this.socket);
  }
}

上面的 this.incoming 就是我们的 IncomingMessage 对象。其中主要的一段逻辑是

1
2
3

const ret = stream.push(slice);
if (!ret)
  readStop(this.socket);

它会向 IncomingMessage 中添加新的数据，如果返回值为 false，则会调用 readStop 方法。该方法会将 socket 流暂停：

1
2
3
4

function readStop(socket) {
  if (socket)
    socket.pause();
}

两者在这块会有一个联系了。

4.4. Stream 的机制

根据上面的实现，可以知道：向 IncomingMessage 流添加数据时如果返回 false，则会暂停 Socket 流。下面结合 Stream 本身的机制，来看下是如何影响到超时定时器的清除的。

首先，是关于 .push 的返回值。

Stream 会有水位控制（highWaterMark），如果一个可读流被不断 push 进数据，但是没有被消费，这时候 Stream 会把这些数据“暂存”在内部，等待消费。显然，如果无限制存储数据，就可能出现内存问题，所以 Node.js 通过返回 false，来建议用户不要再继续写入了。

其次，是关于暂停流。

可读流如果被暂停，除了内部的暂停状态被置为 true 之外，还有一个改变是它的消费模式（reading mode）将会从 flowing mode 变为 pause mode：

1
2
3
4
5
6
7
8
9
10

Readable.prototype.pause = function() {
  debug('call pause flowing=%j', this._readableState.flowing);
  if (this._readableState.flowing !== false) {
    debug('pause');
    this._readableState.flowing = false;
    this.emit('pause');
  }
  this._readableState[kPaused] = true;
  return this;
};

它们的一大区别就是暂停模式下，’data’ 监听不会收到事件，需要手动调用 stream 的 .read 方法来读取数据。

所以，大致原因就是，在我们没有消费 IncomingMessage 的情况下，由于响应体过大，超过最高水位线后，Node.js 就把 Socket 流暂停了，导致无法触发 Socket 的结束销毁，间接导致控制超时的定时器没有被销毁。

5. 再谈如何修复

5.1. 方法一

本文最开始，我们通过添加一段看似毫无意义的代码：

1

res.on('data', () =%&-g-t% {});

解决了这个问题。到这里我们应该理解为什么这段修复代码有效。当然，还有其他两个情况下，该问题也不会发生。

5.2. 方法二

第二个是不给 http.request 添加 callback。例如把 client.js 代码变为：

1
2
3
4
5
6
7
8
9
10
11
12
13

const http = require('http');

// 发送请求，但是没有添加回调函数
const req = http.request({
    port: 8088,
    timeout: 5000,
});
req.end();
req.on('timeout', () =%&-g-t% console.log('request timeout!'));

// 每秒输出一下时间
let i = 0;
setInterval(() =%&-g-t% console.log(1e3 * ++i, 'ms passed'), 1e3);

可以看到，这种情况下并未触发 timeout。

这是因为我们如果不添加回调（同时也不监听 response 事件），IncomingMessage 就会进入 dumped 状态：

1
2
3
4
5

// If the user did not listen for the 'response' event, then they
// can't possibly read the data, so we ._dump() it into the void
// so that the socket doesn't hang there in a paused state.
if (req.aborted || !req.emit('response', res))
  res._dump();

这个状态下，便不会再向 IncomingMessage push 数据，也就没有了后面的事儿。

5.3. 方法三

第三个方式是让服务端不要返回超过 16KB 的响应体。当然这从实际需求来说不太可行，但从原理上来说可以规避这个问题。

因为 highWaterMark 的默认值就是 16KB：

1
2
3

function getDefaultHighWaterMark(objectMode) {
  return objectMode ? 16 : 16 * 1024;
}

我们可以尝试把 server.js 中的返回值长度减小一些：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const http = require('http');

http.createServer(function (req, res) {
    console.time('server-response-end');
    const timer = setInterval(() =%&-g-t% {
-       res.write('1'.repeat(1e5));
+       res.write('1'.repeat(1e2));
    }, 20);

    setTimeout(() =%&-g-t% {
        clearInterval(timer);
        console.timeEnd('server-response-end');
        res.end();
    }, 2000);
}).listen(8088);

这样也不再会误触超时问题。

6. 详细的故障场景

KProxy 是怎么触发这个问题的呢？

作为代理服务器，KProxy 大致工作方式如下：

它在收到用户的请求时（请求 A），会通过 http.request 创建一个到真实服务端的连接（请求 B），将请求 A 的 OngoingMessage pipe 给请求 B，然后将请求 B 的 IncomingMessage pipe 给请求 A。

这个方式本身没有问题，但在一个特殊的功能下，会出现问题。

KProxy 可以支持完全覆盖响应体，在这种情况下，KProxy 会将请求 B 的响应头和用户设置的响应体直接拼接，形成完整的响应内容 pipe 给请求 A。可以看到，这里主要的区别就是，不会消费响应体（IncomingMessage）。但它仍然监听了 http.request 的回调。同时，由于该代理请求的响应体正好超过了 16KB，就导致了「请求理论上应该结束，但却“误报”超时」的问题。

7. 最后

由于本文结合源码阐述了该问题的原因，并且介绍了一些相关的基础知识，所以篇幅较长。精简来说：

• http 模块中，IncomingMessage 的写入状态会影响 Socket 流的启停状态，从而可能导致 Socket 流无法如期调用其 destroy 方法。
• 如果不关心响应信息，可以不要添加回调或 response 监听，否则可能由于触及 highWaterMark 而导致上面的情况，甚至引起一些内存问题

此外，再补充一点与该故障无关也相关的点，Readable Stream 如果没有被消费，不会触发 end 事件。所以下面的代码也是不会打印 ‘finish’ 的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

const http = require('http');

// 发送请求
const req = http.request({
    port: 8088,
    timeout: 5000,
}, res =%&-g-t% {
    res.on('end', () =%&-g-t% console.log('finish'))
});
req.end();

// 每秒输出一下时间
let i = 0;
setInterval(() =%&-g-t% console.log(1e3 * ++i, 'ms passed'), 1e3);

除非也给它加上 res.on('data', () =%&-g-t% {}) 这段代码。

近期在做 Node.js 基础监控中 Active Handles/Requests 信息的按需采集功能。在 Active Handles 中包含了 timer 的信息采集，这里的 timer 就是指的通过 setTimeout/setInterval 设置的定时器，以及 Nodejs 内置 JavaScript 模块中创建的定时器等。而 Nodejs 在 timer 实现上与其他异步资源的代码结构不太一致，做了特定的优化。

本文源码基于 v14.17.3。其主要逻辑与概念在近四个双数版本（v10/12/14/16）上基本一致。

1. 引言

在上篇中我们介绍了 Handles 和 Requests 的概念，了解了什么是 Active 状态。并且知道了一个信息 —— Nodejs 使用了 HandleWrap 这个基类来作为 libuv 中 Handle 的封装，所以我们有两种获取 Handle 的方式：

• 遍历 HandleWrap Queue
• 使用 uv_walk 来遍历

但在上篇中提到，通过上面的方式采集，有一个例外，就是定时器（timer）：

• HandleWrapQueue 中是没有 TimerWrap 的，所以通过这种方式，是拿不到 js 层设置的定时器的；
• uv_walk 中拿到的 timer handle，与 js 层设置定时器的情况也差异极大，并不能反映其情况。

那么这篇内容会接着从 Node.js 中 Timer 的实现，来解释「为什么 HandleWrapQueue 中没有 TimerWrap」，为什么「libuv 中的 timer handle 信息与 js 的 timer 对不上」。

2. 真的没有 TimerWrap 么？

有也没有。

Nodejs 中要用到的其他类型的 Handle，基本都会有对应的 HandleWrap，但我们却找不到 Timer Handle。不过它曾经有过。

如果你去看 Nodejs 的早期版本（例如 6 年前的 v2.0.0），会发现实际是有 time_wrap.cc 这个文件的：

我们在 userland 里设置的定时器，就会间接使用到它。然后，在 v11.0.0 中被移出。移除它的一个原因也是因为在多个版本迭代后，已经不再需要向 js 层暴露创建 native 定时器的能力。这和 Timer 的实现也很有关系。

3. libuv 中 timer 的实现

我们以 v14.17.3 配套的 libuv v1.47.0 为例来看下其中 timer 的实现。

libuv 会使用 heap 来存储所有的 timer handle。在调用定时器的 start 方法时，会插入堆中，而 stop 则会从 heap 里移除：

1
2
3
4
5
6
7
8
9
10

int uv_timer_start(uv_timer_t* handle,
                   uv_timer_cb cb,
                   uint64_t timeout,
                   uint64_t repeat) {
  ...
  heap_insert(timer_heap(handle-%&-g-t%loop),
              (struct heap_node*) &handle-%&-g-t%heap_node,
              timer_less_than);
  ...
}

在核心的循环方法 uv_run 中则有一个阶段是执行定时器的：

1
2
3
4
5
6
7
8
9
10
11
12

int uv_run(uv_loop_t* loop, uv_run_mode mode) {
  ...
  r = uv__loop_alive(loop);
  if (!r)
    uv__update_time(loop);

  while (r != 0 && loop-%&-g-t%stop_flag == 0) {
    ...
    uv__run_timers(loop);
    ...
  }
}

它实际上就是从 heap 中遍历所有到期的定时器来执行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

void uv__run_timers(uv_loop_t* loop) {
  struct heap_node* heap_node;
  uv_timer_t* handle;

  for (;;) {
    heap_node = heap_min(timer_heap(loop));
    if (heap_node == NULL)
      break;

    handle = container_of(heap_node, uv_timer_t, heap_node);
    if (handle-%&-g-t%timeout %&-g-t% loop-%&-g-t%time)
      break;

    uv_timer_stop(handle);
    uv_timer_again(handle);
    handle-%&-g-t%timer_cb(handle);
  }
}

4. Nodejs 在使用 timer 时面临的问题

libuv 中实现定时器的逻辑并不复杂。但是这种情况下，在实际的应用中可能会有些问题。

在大多数 Node.js 应用中，定时器的创建会很频繁。我们也许只注意到自己使用的 setTimeout/setInterval，但像是发起 http 请求时的 timeout，处理 incoming message 时的 timeout 等等，这些都会涉及定时器。

试想一下，我们 1 个接口对应 3 个后端请求的话，处理一个请求就会用到 4 个定时器，处理 1000 个请求就会要创建 4000 个定时器。那么这里可能就有两部分不好忽视的开销：

1. timer 插入 heap 的时间
2. js 与 C++ 之间的频繁调用，因为需要不停创建 TimerWrap

那么有办法优化么？

5. 借鉴 libev，优化 timer 实现

与 libuv 类似，有一个叫 libev 的异步事件库，它介绍了优化 timer 的一些思路。Node.js 参考了它的思路。

但这块其实有过两次优化调整。下面先来介绍第一次优化，看看它是如何降低 timer 的 start、stop、处理到期 handler 这三个操作的时间复杂度。

Node.js 运用了一个假设（或者说是先验知识）：很多 Timer 都会具有同样的 timeout 值。它是该优化手段的基础。

这里的 timeout 值可以理解为 setTimeout 和 setInterval 的第二个参数，也就是那个毫秒参数。正如刚才说的，一般大批量的定时会在像是 http timeout 这种场景下产生；或者我们在写代码时，大多也是设置固定时间的定时器。那么 timeout 就是可枚举的。我们可以把 timeout 相同的 timer 存入一个双向链表中。每个链表会对应创建一个 TimeWrap(TimeHandleWrap)，负责顺序触发这个链表中的 timer。

结构如下：

由于链表是按 timer 创建的时间顺序插入，所以顺序触发即可，不需要额外的遍历。

先来看 stop 操作，即移除 timer。显然，移除双向链表某一节点的复杂度是 O(1)。再来看 start，也就是插入操作。目前，插入需要遍历所有 TimerList 找到该 timeout 对应的链表。那么很容易想到的优化就是基于 timeout 值加哈希映射。在 js 中可以用类似 map (object) ：

那么在插入的时候可以先通过 Map 找到链表，再在链表尾部插入，整个操作维持在 O(1)：

最终就是如下的数据结构：

Node.js 在 js 层维护了主要的数据结构，而每个 timeout 值对应的 C/C++ timer handle 会在触发时通过 binding 获取并调用 js callback。

6. 进一步的优化

在做完上面的优化之后，已经大幅减少了实际的 timer handle 的创建，不再需要每次添加定时器时都走一遍 js -%&-g-t% C++ 的调用；同时，还将操作复杂度从 O(lgN) 降为了 O(1)。而在这个情况下，Node.js 在 v11.0.0 中又进行了一次 timer 结构的调整。

在这个 PR 中，每个 Node.js 环境只需要一个 timer handle，不再需要每个 timeout 值就创建一个 TimerWrap(timer handle) 了。

如何只使用一个实际的 TimerWrap 来处理可能出现的所有 js 中的 timer 呢？其中主体数据结构与第五节相同，仍然是 Map + Doubly Linked List 的组合来保证插入和移除效率。

但为了能够让 TimerWrap 快速找到下一个需要执行的定时器，其新增了一个 heap 来存储所有的链表头。这个链表头是一个特殊节点，会存储该链表中第一个 timer 的到期时间，因此结构就变为：

通过取出堆顶元素，就可以拿到需要执行的 timer。然后再对堆进行整理，并将最新的堆顶元素的到期时间设置给 TimerWrap，保证下次按时触发。虽然堆上插入、删除的复杂度是 O(log N)，但如果我们以之前的假设来看（即 timer 数量虽多，但都是集中的几个 timeout 值），那么这个堆的大小其实也是一个很小的常数，因此实际的时间开销并不大。

7. 不再需要 TimerWrap

介绍完了 Node.js 中的优化，大家可能也发现为什么不再需要 TimerWrap 了。

Wrap 的作用是提供给 js 层创建 uv handle 的能力。但经过优化，只存在一个 timer handle 了，那么完全就可以在 Node.js 启动时创建出来，不再需要 js 层根据情况动态创建 timer handle 了。所以也就不再需要了。

而更准确的来说，应该是每个 Node.js Environment 会有一个对应的 timer handle。例如像我们创建了一个 worker，就会有一个新的“环境”。

8、更“准确”的 timer 情况

从上面的内容可以知道，「timer」的含义在不同场景下含义可能不同：

• 当我们在 libuv 的语境中，timer 就是 timer handle；
• 当我们在 js 层的语境中，它会是 js 中创建的 timer 对象。

两个信息具有较大的不一致性。例如仅仅提供 timer handle 的信息，那么就无法知道 userland 中实际创建的 js timer 的情况。而反过来，如果一些 C++ Add-on 创建了 timer handle，那么从 js timer 中也是不到这个信息的。

总结

timer 作为 Node.js 中高频使用的功能，被针对性进行了很多优化。其中一大优化就是数据结构上的优化。

Node.js 中通过 Map + Doubly Linked List + Heap 来保持定时器的高校插入、删除和触发的同时，将实际使用的 timer handle 的数量优化为 1 个，这也大幅减少了 js 与 C++ 相互调用的次数。

近期在做 Node.js 基础监控中 Active Handles/Requests 信息的按需采集功能。在 Active Handles 中包含了 timer 的信息采集，这里的 timer 就是指的通过 setTimeout/setInterval 设置的定时器，以及 Nodejs 内置 JavaScript 模块中创建的定时器等。而 Nodejs 在 timer 实现上与其他异步资源的代码结构不太一致，做了特定的优化。

本文源码基于当前（2021.07.18）的 LTS 版（v14.17.3）。其主要逻辑与概念在近四个大版本（v10/12/14/16）上基本一致。

1. 引言

由于部分同学可能对 Nodejs 中的 Handles 和 Requests 不太熟悉，所以本文会分为上下两篇：

• 上篇先介绍 Active Handles & Requests 和的基本概念作为铺垫，不会涉及 timer 部分。

• 下篇会介绍 timer “与众不同”的地方，以及 Nodejs 为其定制的优化。

2. 什么是 Handles 和 Requests？

提到 Nodejs 中的 Handles 和 Requests 时，我们指的就是 libuv 中的 Handles 和 Requests 概念。

可以大致理解为 Handle 会”指代“一系列 I/O 操作或 timer 等，例如用于 TCP 的 uv_tcp_t，用于定时器的 uv_timer_t。libuv 中还有一个与其类似的概念是的 Request，它与 Handle 的主要区别就是生命周期的长短。

Handles represent long-lived objects capable of performing certain operations while active.
—— libuv design overview

例如我们最常见的 DNS 查询（uv_getaddrinfo_t）和文件读写（uv_fs_t）就都是 Request。

Nodejs 中的一个核心依赖就是 libuv。它通过 libuv 来实现基于 event loop 模型的异步 I/O，同时抹平了系统间的差异。由于 Handle 会“指代”某个工作，因此通过 Handle（与 Request）的信息也可以一定程度上反应出 Nodejs 目前在忙些什么事儿。

我们在 userland 里做的各种 I/O 操作，最后很多都会直接对应到 libuv 中的 Handle。

上面是从 Handle 角度来看，我们使用 Nodejs 时的大致情况。

日常工作中我们大多都是在 userland 写代码（包括引入的 npm 包）。这些代码会引用（require）各个 Nodejs 内置模块，也就是图中的 internal javascript module。然后最底层是通过 libuv 的 public API 来创建 Handle 并进行异步 I/O。为了能让 js 层使用到最底层的 uv 库，Nodejs 中有一部分代码会负责做 Handle 的包装，加上一些简单的处理逻辑，再通过 v8 binding 机制暴露给 Nodejs 的内部 js 模块，也就是图中 Handle Wrap 和 v8 bindings 这部分。

Handle Wrap 在 node-core 中就是指的 src 目录下实现的 ProcessWrap / FSEventWrap 这些，它们是对 libuv 中 handle 的封装，都继承自 HandleWrap 抽象类。下图是 HandleWrap 和 ReqWrap（libuv Request 的 Wrap）类相关的类继承关系。

其中浅蓝色部分的 AsyncWrap 是对 Nodejs 中异步操作的抽象，会用来做异步的追踪，例如在 userland 中使用的 async_hooks 中的一些功能就会依赖到这部分。绿色部分的 BaseObject 和 MemoryRetainer 则是用于那些在 JavaScript 层和 C/C++ 层有对应关系的对象时，帮助管理对象的生命周期。

3. 什么是 Active 状态？

上面介绍了 Handles 和 Requests。下面说说 Active 的概念。

Active 是 libuv handle 的一种状态。一般某种 handle 都会存在对应的 uv_xxx_start() 和 uv_xxx_stop() 方法。在调用 uv_xxx_start() 后 handle 就会进入 active 状态；而在调用 uv_xxx_stop 方法后，handle 就会被 deactivate。因此，通过找到所有的 Active Handles，可以一定程度上了解目前 Nodejs 进程正在或将要干什么事儿。

而在 Nodejs 进程运行时，会通过调用 uv_loop_alive 来检查是否存在 active handles & requests，从而判断进程是否需要退出。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

do {
    uv_run(env-%&-g-t%event_loop(), UV_RUN_DEFAULT);

    per_process::v8_platform.DrainVMTasks(isolate_);

    more = uv_loop_alive(env-%&-g-t%event_loop());
    if (more && !env-%&-g-t%is_stopping()) continue;

    if (!uv_loop_alive(env-%&-g-t%event_loop())) {
        EmitBeforeExit(env.get());
    }

    more = uv_loop_alive(env-%&-g-t%event_loop());
} while (more == true && !env-%&-g-t%is_stopping());

上面代码中 uv_run 和 uv_loop_alive 两个方法都与是否存在 active handle 有关。Nodejs 进程是否退出也与它们的执行情况有关。 uv_loop_alive 方法会判断是否有 active 状态的 handles 和 requests。

uv_run 则是会不断循环从各个“队列”中取任务执行，在 UV_RUN_DEFAULT 模式下，只有在没有 active handle/request 时，该方法才会跳出循环并返回：

1
2
3
4
5
6
7
8
9
10
11

int uv_run(uv_loop_t* loop, uv_run_mode mode) {
    ...
    while (r != 0 && loop-%&-g-t%stop_flag == 0) {
        ...
        r = uv__loop_alive(loop);
        if (mode == UV_RUN_ONCE || mode == UV_RUN_NOWAIT)
            break;
    }
    ...
    return r;
}

从那个上面代码可以看到，DEFAULT 模式下 uv__loop_alive 的返回值将决定 event loop 是否持续。而 uv_loop_alive 内部实际调用的也是 uv__loop_alive。

这就是为什么下面这段代码在运行后，Nodejs 进程不会退出

1
2
3

const http = require('http');
const app = http.createServer(() =%&-g-t% {})
app.listen(8088);

因为在 Nodejs 进程中存在一个 TCP 的 active handle。

4. unref handles

但 libuv 中有一个特殊的操作叫 unref（解引用），可以让实际 “active” 的 handle 不会在 uv_loop_alive 中被统计到。

每个 event loop 中会维持一个 active_handles 属性用于计数（requests 也类似），在 uv_loop_alive() 中会通过 uv__has_active_handles 宏来判断是否大于 0。

1
2

#define uv__has_active_handles(loop)    \
  ((loop)-%&-g-t%active_handles %&-g-t% 0)

而使用 uv_unref() 来解引用，最后就会通过 uv__active_handle_rm 来将该计数减一。

1
2
3
4
5

#define uv__active_handle_rm(h)     \
  do {                              \
    (h)-%&-g-t%loop-%&-g-t%active_handles--;    \
  }                                 \
  while (0)

但这只是减少了 active_handles 计数，并不会影响 handle 的执行。所以只要进程还未退出，handle 的工作就会正常做。而 Nodejs 也将 unref 操作封装暴露到了 userland 里，基本上如果我们在 userland 中创建的对象有对应的 handle，都会在其上存在一个 .unref() 的方法。例如还是上面这段代码，当我们稍作修改

1
2
3
4

const http = require('http');
const app = http.createServer(() =%&-g-t% {})
app.listen(8088);
+ app.unref();

这个时候如果再去运行，进程立刻就退出了。

5. 什么时候会用到 unref？

也许你会奇怪，为什么需要 unref 呢？像上面这段代码，创建了一个 HTTP 服务监听端口，是不希望退出的。但可以考虑另一个场景：

• 我们要读取文件执行一批异步任务，任务结束后进程退出。
• 同时，希望每 5 秒上报一下环境信息。

最简版本：

1
2
3
4
5
6
7
8

// do batch tasks
const fs = require('fs');
fs.readFile('task.txt', 'utf-8', (_, content) =%&-g-t% {
  doBatchAsyncTasks(content.split(','));
});

// report
const timer = setInterval(reportEnvStat, 5000);

但这个版本的一大问题就是，任务结束后进程并不会退出，因为进程中有一个会“永久”存活的 timer handle。处理这种问题有几个可行方式：

1. doBatchAsyncTasks 结束后直接调用 process.exit() 来主动退出；
2. 在 doBatchAsyncTasks 后，通过 clearInterval() 来清除定时器。

但这两种方法，都会导致设计上的耦合 —— 异步任务和定时上报需要嵌套对方的资源。

另一种更简便的方式，就是使用 .unref()：

1
2
3
4
5
6
7
8

const fs = require('fs');
fs.readFile('task.txt', 'utf-8', (_, content) =%&-g-t% {
  doBatchAsyncTasks(content.split(','));
});


const timer = setInterval(reportEnvStat, 5000);
+ timer.unref();

这在你实现一个 library 时可能会更典型。如果你的 library 中创建了一个“永久”的 active handle，而其独立存活并无意义的话，就可能导致使用它的进程无法在预期状态下退出。而这种情况 1、2 这两种方法可能就不太合适， 使用 unref 就会好些。

6. 如何采集 Active Handles？

那我们如何获取当前进程中的 Active Handles 呢？

一个最简单的思路是，在所有 handle 创建的地方（或者统一入口），存储其信息；然后在所有 stop 的地方删除掉存储的对象。但由于 Nodejs 运行过程中 handles 的数量并不少，创建也很频繁（很多时候和 QPS 成正比），所以这种方式在运行时性能与内存占用上都有明显缺陷。

因此会借助目前 Nodejs 已有的能力。其本身已经存储了创建的 Handles 与 Requests 对象。这样只有在按需触发采集时才会有性能与内存开销，采集完毕后又恢复如初。

在 Nodejs 中有两个比较可行的「采集点」：

1. libuv 提供了 uv_walk() 这个 public API 来遍历某个 event loop 中所有的 Handles，包括 active/inactive、ref/unref。
2. Nodejs 也会保存其所创建的 HandleWrap 对象。通过文章之前的部分可以知道，该对象与 libuv handles 有对应关系，保存了指向 libuv handle 的指针。

对于第一种方法，可以传入一个回调函数来处理遍历到的 handles。libuv 内部会把 handles 保存在 event loop 的 handle_queue 上，通过遍历该队列 libuv 就可以拿到所有 handles。

第二种方式，则可以通过 Nodejs Environment 对象上的 handle_wrap_queue() 方法来获取 HandleWrapQueue 的指针，它是一个双向链表，用存储当前环境下所有的 HandleWrap 对象。

由于之前我们提到的，两者存在对应关系，所以基本上从这两处都可以获取到所需的 handle 详情信息。

7. 例外情况：定时器（timer）

通过上面的方式采集，有一个非常重要的例外，就是定时器（timer）：

• HandleWrapQueue 中是没有 TimerWrap 的，所以通过这种方式，是拿不到 js 层设置的定时器的；
• uv_walk 中拿到的 timer handle，与 js 层设置定时器的情况也差异极大，并不能反映其情况。

所以，为什么 HandleWrapQueue 中没有 TimerWrap？为什么 libuv 中的 timer handle 信息与 js 的 timer 对不上呢？

这两个问题会留到「Nodejs 中的 Active Handle 与 Timer 优化（下）」中继续介绍。

总结

最后总结一下本文内容：

1. Handles 和 Requests 是 libuv 中的抽象概念，一种 Handle 大致指代了一种 I/O 操作。
2. node-core 中对各类 Handles 与 Requests 进行了封装，并分别继承自 HandleWrap 和 ReqWrap。
3. Active Handles/Requests 代表当前进程正在忙或将要忙的事儿，它也是 Nodejs 进程不退出的重要原因。
4. 使用 .unref() 方法可以在不“取消” handle 工作的同时，解除该 handle 的 active 计数。
5. 可以通过 uv_walk 或 env-%&-g-t%handle_queue() 来收集大多数 handle 信息。

某天下午，线上的服务监控发出报警：在同一个服务下，部署的众多容器中，某一个容器出现 OOM 问题。

1、OOM 报警：内存泄漏？

上图是容器维度的资源使用率监控图。可以看到红色的内存使用率曲线，逐步升高将近到 100% 后又迅速降至 0%。这是因为触发 OOM 后容器自动重启。而在重启后，容器的的内存使用率仍在缓慢上升。

该容器分配的资源为 1 核 1G，其容器内只运行一个 Nodejs 进程。运行的 Nodejs 进程在某段时间的监控曲线如下：

可以看到，堆内存使用率也是逐步攀升，CPU 使用率则较为稳定。其与容器维度的监控表现一致。从容器与 Nodejs 进程的曲线上来看，非常像是 Nodejs 服务内存泄漏的问题。

2、使用堆内存快照，排查堆内存问题

既然是内存问题，我很快想到要通过堆内存快照（Heap Snapshot）来排查。该服务使用了快手内部自研的 KNode 运行时来部署服务，因此可以在线上按需实时地打出堆快照，并在线查看：

Heapsnaphost 中各项的含义以及如何查看，如果不了解可以看 Chrome Devtools 的说明文档。

不过可能是由于堆快照是一个切面数据，同时，打印这张快照时堆内存使用率也不是太高（大概为 20%），所以在初步看了堆快照后，问题线索不太直接。遇到这个问题，还有一个好办法，就是做两个时间点的快照 Diff。

v8 会给每个堆内存对象分配一个 ID。因此可以在 Heap 使用率较低和较高两个时间点，分别打印对应的堆快照，通过这个关联 ID，就可以对比出这段时间内新增和回收释放的堆内存对象。而 Chrome Devtools 本身也支持堆快照的 comparison 展示。

上图展示了在堆内存从 20% 涨到 50% 后新申请而没有被 GC 的对象（Object Allocated）。结合之前的堆快照（切面数据）和上面的 comparison 数据（Diff 数据），可以发现，红框中的这两类对象非常突出。也就是 GetAddrInfoReqWrap 与 Socket。

Socket 和网络连接相关，属于比较广的范围。因为我将目光放在了 GetAdrrInfoReqWrap 上。基于之前对 Nodejs 的了解，我知道这是和 DNS 查询相关的 JS 层 wrapper 对象。当然，如果大家不知道这个对象，也可以通过查阅 Nodejs 源码来了解到它的功能。展开堆快照中的对象，看下具体信息：

从快照中对象的具体信息看，其 hostname 比较分散，所以感觉是和容器内整个 DNS 查询有关。

3、从其他 Nodejs 监控项，来看这个问题

如果是 DNS 查询的问题，肯定也会间接影响到 HTTP 相关的监控项。而情况也确实如此。从 Nodejs 进程发起的 HTTP 请求的监控来看，有问题的容器，每分钟能完成的请求数只有 3 次（如下图）：

而同一个服务下的正常容器内，每个 Nodejs 进程每分钟可以正常发送超过 150 个 HTTP 请求（如下图）：

同时，异常容器中的 Nodejs 发送完成一个 HTTP 请求的平均耗时超过了 800 秒（%&-g-t%13分钟）。而正常情况下内网服务之间的 HTTP 请求耗时一般都在几十毫秒，慢的也不太会超过几百毫秒。

此外，如果查看 Nodejs 的 Active Handle 的数量，也是处于一个持续上涨的状态。

这里的 Active Handle 是指 libuv 中的 Handle，与其类似的还有一个叫 Request 的概念。它是 libuv 中的抽象概念，用来指代 libuv 中某项操作的对象，例如定时器、设备 IO 等。Nodejs 进程中的 Active Handle 数量持续上涨往往是有问题的，它说明 Nodejs 要处理的东西“积压”地越来越多。

因此，基本怀疑就是 DNS 查询的问题导致请求积压，从而导致了该故障。

4、故障确定与修复

通过上面的分析，基本可以确定和 DNS 查询脱不了干系。因为在服务部署的众多容器中，只有这一个有 OOM 问题，所以我分别登进一个健康容器和这个问题容器，执行以下 JS 代码来确认 DNS 查询情况（本文隐去了实际域名）：

1
2
3
4

console.time('dns');
require('dns').lookup('xxx.xxxx.xxx', () =%&-g-t% {
    console.timeEnd('dns');
});

这里需要提一下。Nodejs 封装了两类 DNS 查询的方法，一类就是上面用到的 dns.lookup()；另一个就是 dns.resolve() 和 dns.resolve*()。这里之所以在测试代码中使用 dns.lookup() 方法，是因为使用 Nodejs 中内置 http 模块的 http.request() 请求时，默认使用的就是该方法，而不是 dns.resolve()。

项目使用了 axios，而其在 Nodejs 环境下使用的是 http.request() 方法来发起 HTTP 请求。http.request() 会调用 net 模块中的 createConnection 方法来建立连接。net 模块创建连接时，默认的 lookup 方法就是 dns.lookup()：

1
2
3
4
5
6
7
8
9
10

function lookupAndConnect(self, options) {
  // ...
  const lookup = options.lookup || dns.lookup;
  defaultTriggerAsyncIdScope(self[async_id_symbol], function() {
    lookup(host, dnsopts, function emitLookup(err, ip, addressType) {
      self.emit('lookup', err, ip, addressType, host);
      // ...
    });
  });
}

当然，lookup 方法是可以设置的，例如可以传入 dns.resolve() 或者自定义的方法。下图就是 Nodejs 官方文档中的说明截图：

回到该故障。测试代码运行后，正常容器（下图左）的 DNS 查询耗时为 33 毫秒；故障容器的耗时为 5000 毫秒，差异极大。

那么是什么导致的耗时差异呢？

dns.lookup() 方法会使用系统的 /etc/resolv.conf 配置文件。该文件中会设置 nameserver 的地址、超时时间、重试次数、rotate 策略等。通过对比正常容器和故障容器，发现了配置差异：

故障容器中（上图右）有个 nameserver 配置为了 10.62.38.17（正常容器是 10.6.6.6）。而 10.62.38.17 这个 nameserver 之前出现了问题，已经被替换掉了。但是在基础平台批量刷配置的操作中，故障容器所属的宿主机可能遗漏或者失败了。定位到具体原因后，联系了司内的容器化部署/运营平台的同学，修复该配置后后故障就解决了。

5、总结

这个问题曲折的点在于：其监控表象初看像是内存泄漏，而一般来说内存泄漏都是代码 bug 导致的。但这个故障其实并非如此，实际是宿主机 DNS nameserver 的配置问题。

原因大致就是，由于 Nodejs 中 DNS 查询耗时过长导致了请求堆积，上游服务与 Nodejs 建立的连接也不会释放。所以在整个请求的生命周期中「持有」的对象未被释放，堆内存中对象不断增多，从而看起来像是「内存泄漏」。

加餐：聊聊 Nodejs 中 DNS 查询与请求堆积

上面还是只一个粗略的分析和定位。在这一节会尝试能更深入一些，将故障现象和 Nodejs 实现细节联系起来。

关于 Nodejs 中 DNS 查询故障导致的服务不响应的问题，之前已经有文章阐述了类似的问题：

• node中请求超时的一些坑
• NodeJS 中 DNS 查询的坑 & DNS cache 分析

下面再尝试简单解释一下。

使用 http 模块的 http.request() 方法默认会使用 dns.lookup() 作为 DNS 查询的方法（这个在上中文也已经提到了）。而 dns.lookup() 通过 binding 会调用到 GetAddrInfo() 函数：

1
2
3
4
5
6
7
8
9
10
11
12
13

void GetAddrInfo(const FunctionCallbackInfo%&-l-t%Value%&-g-t%& args) {
  // ...
  int err = req_wrap-%&-g-t%Dispatch(uv_getaddrinfo,
                               AfterGetAddrInfo,
                               *hostname,
                               nullptr,
                               &hints);
  if (err == 0)
    // Release ownership of the pointer allowing the ownership to be transferred
    USE(req_wrap.release());

  args.GetReturnValue().Set(err);
}

其中最重要的调用的就是 uv_getaddrinfo()，它会将 uv__getaddrinfo_work 提交到线程池的工作任务中：

1
2
3
4
5

uv__work_submit(loop,
                &req-%&-g-t%work_req,
                UV__WORK_SLOW_IO,
                uv__getaddrinfo_work,
                uv__getaddrinfo_done);

而 uv__getaddrinfo_work() 中就会使用 getaddrinfo 函数来做 DNS 查询：

1
2
3
4
5
6
7
8

static void uv__getaddrinfo_work(struct uv__work* w) {
  uv_getaddrinfo_t* req;
  int err;

  req = container_of(w, uv_getaddrinfo_t, work_req);
  err = getaddrinfo(req-%&-g-t%hostname, req-%&-g-t%service, req-%&-g-t%hints, &req-%&-g-t%addrinfo);
  req-%&-g-t%retcode = uv__getaddrinfo_translate_error(err);
}

那么为什么会涉及到线程池概念呢？因为调用 getaddrinfo() 函数是一个同步调用，所以 libuv 会通过线程池来实现 Nodejs 所需的异步 IO。线程池默认大小为 4，可以通过 UV_THREADPOOL_SIZE 这个环境变量来配置，在 Nodejs v14 中最大是 1024。

回到故障场景：

从正常进程的监控数据看到，每分钟 Nodejs 进程发起的请求大致为 150 个，也就是 1 秒 2.5 个。而在故障容器中，请求在 DNS 查询阶段就要耗时 5s。即使不考虑其他耗时也要 5s 才能发完一个请求。4 个线程平均下来，也就是 1 秒最多能处理 0.8 个请求。显然，2.5 要远大于 0.8，处理能力和请求数量严重不匹配。所以服务运行时间越长，积压的请求数、连接数就越多。

到这里，还有几个问题可以再说明下：

关于超时

对于 HTTP 请求，我们一般会设置超时时间。但是 Nodejs 发起的请求可能不会触发到超时，由此使得上游服务到 Nodejs 的连接不会及时断开。这是在使用 axios 时可能出现的问题。

因为 axios 会基于 requset.setTimeout 来设置超时。之前的文章也分析过，它是不包含 DNS 查询时间的。从 Nodejs 官网文档中也能大致看出这个意思。

关于 DNS cache

Nodejs 本身不做 DNS 查询结果的缓存（一些讨论也认为 cache 放在 userland 可能会合理些）。所以如果 getaddrinfo() 本身也没有 DNS cache（开启 nscd 似乎可以），Nodejs 就会在每次使用域名做 http 请求时，都会去请求 DNS nameserver。上文故障中的情况便是如此。

当然，你也可以通过使用类似像 dnscache 这类包来做 monkey patch，在 JS 层为 DNS 查询添加缓存；或者通过在 axios 中添加拦截器，实现缓存。不过使用缓存一定要注意处理缓存过期的问题，可以使用 DNS server 返回的 TTL。不过有时这个值也不太可靠，可能会需要基于业务场景设置一个尽量小的值。总之使用缓存一定要谨慎！

关于 dns.resolve()/dns.resolve*()

从文章之前的章节可以知道，dns.resolve()/dns.resolve*() 与 dns.lookup() 的实现并不相同。它们是基于 c-ares 实现的。

This is c-ares, an asynchronous resolver library. It is intended for applications which need to perform DNS queries without blocking, or need to perform multiple DNS queries in parallel.

http.request() 是支持通过在 options 中传入 lookup 配置来覆盖默认的 dns.lookup 的。但是需要注意 dns.resolve() 和 dns.lookup 存在的可能区别。

此外，它们只是不用再使用线程池，如果遇到像文中的故障，DNS 查询的耗时一样会很高，同样会有类似问题。

完。

近期，在线上运行服务时遇到了一个诡异的 Linux 权限问题：root 用户在操作本该有权限的资源时，却报了权限错误。

1、问题背景

报错如下：

1
2
3
4
5
6
7
8
9
10
11

Error: EACCES: permission denied, mkdir '/root/.pm2/logs'
    at Object.mkdirSync (fs.js:921:3)
    at mkdirpNativeSync (/home/web_server/project/node_modules/pm2/node_modules/mkdirp/lib/mkdirp-native.js:29:10)
    at Function.mkdirpSync [as sync] (/home/web_server/project/node_modules/pm2/node_modules/mkdirp/index.js:21:7)
    at module.exports.Client.initFileStructure (/home/web_server/project/node_modules/pm2/lib/Client.js:133:25)
    at new module.exports (/home/web_server/project/node_modules/pm2/lib/Client.js:38:8)
    at new API (/home/web_server/project/node_modules/pm2/lib/API.js:108:19)
    at Object.%&-l-t%anonymous%&-g-t% (/home/web_server/、project/node_modules/pm2/lib/binaries/CLI.js:22:11)
    at Module._compile (internal/modules/cjs/loader.js:1137:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1157:10)
    at Module.load (internal/modules/cjs/loader.js:985:32)

这个错误非常直观，就是用户想要创建 /root/.pm2/logs 文件夹，但是没有权限。该服务使用 pm2 做多进程管理。pm2 默认会将其日志信息、进程信息等写入到 $HOME/.pm2 下。因为是 root 后用户所以写到了 /root/.pm2 里。

但这个问题的奇怪之处在于，服务是通过 root 用户启动的，对 /root 目录是具有写入权限的。但这里却报了名优权限的错我。

那么是什么导致 root 用户操作 /root 目录的权限“丢失”了呢？

2、初步排查

项目是容器化部署，使用 npm script 启动，代码文件位于 /home/web_server/project 下。执行 npm start 即可启动。

这是我们使用的一套标准的构建与部署「模版」，已经在上百个服务上应用，且一直都正常。知道近期的一次上线出现了上面这个问题。

这次突然出现的这个问题让我充满了疑惑 —— 基于对 Linux 系统用户、用户组权限控制的理解，不可能出现这个错误。难道是我理解有误？

在疑惑的同时，我尝试不使用 npm script，直接通过 pm2 命令行 pm2 start ecosystem.config.js 启动，发现服务正常启动了！莫非是 npm 导致的？

而在这次上线的时候，确实更新了基础镜像，升级了 npm cli。之前是 v6.x，这次更新到了 v7.x。而当我将 npm 版本回退到 v6.x 后，问题小时。看来是 v7.x 的改动导致了这个问题。

3、问题定位

先说结论：npm v6.x 使用 npm script 执行命令时默认会使用 unsafe 模式，将子执行命令的子进程设置为 root 用户/用户组，该行为可以通过 unafe-pem 配置来控制。而在 v7.x 中，如果通过 root 用户执行 npm script，则会基于当前目录（cwd）所属用户来设置。

下面通过代码来一起看下。

3.1、v7.x 中 npm script 的实现

以下代码来自 npm/cli v7.11.1

npm script 的执行逻辑可以从 lib/exec.js 中查看：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class Exec extends BaseCommand {
  // ...
  async _exec (_args, { locationMsg, path, runPath }) {
    // ...
    if (call && _args.length)
      throw this.usage

    return libexec({
      ...flatOptions,
      args,
      // ...
    })
  }
}

省略无关代码，可以看到执行 npm script 时会调用 libexec 方法，libexec 方法内部会调用 runScript 方法来执行命令。

因为调用链比较长，我把中间代码省略了，只贴出关键的代码，感兴趣的朋友可以点击文中链接跳转查看。

通过一系列曲折的调用，代码最后会调用到 promiseSpawn 方法。这个方法最终会使用 child_process 内置模块里提的 spawn 方法来启动子进程执行命令，其相关代码如下：

1
2
3
4
5
6
7
8
9
10
11

const promiseSpawn = (cmd, args, opts, extra = {}) =%&-g-t% {
  const cwd = opts.cwd || process.cwd()
  const isRoot = process.getuid && process.getuid() === 0
  const { uid, gid } = isRoot ? inferOwner.sync(cwd) : {}
  return promiseSpawnUid(cmd, args, {
    ...opts,
    cwd,
    uid,
    gid
  }, extra)
}

上面的实现中，有一行非常重要：

1

const { uid, gid } = isRoot ? inferOwner.sync(cwd) : {}

可以看到，如果当前进程的用户是 root，则会使用 inferOwner 方法来设置启动的子进程的 uid 和 gid（也就是用户 id 和用户组 id）。

那么 inferOwner 是做什么的呢？它其实就是用来获取某个文件所属的用户与用户组的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

const inferOwnerSync = path =%&-g-t% {
  path = resolve(path)
  if (cache.has(path))
    return cache.get(path)

  const parent = dirname(path)

  let threw = true
  try {
    const st = fs.lstatSync(path)
    threw = false
    const { uid, gid } = st
    cache.set(path, { uid, gid })
    return { uid, gid }
  } finally {
    if (threw && parent !== path) {
      const owner = inferOwnerSync(parent)
      cache.set(path, owner)
      return owner // eslint-disable-line no-unsafe-finally
    }
  }
}

其中最重要的代码是这几行：

1
2
3

const st = fs.lstatSync(path)
// ...
const { uid, gid } = st

fs.lstatSync 方法 会使用 fstat 这个系统调用来获取文件的 uid 和 gid。

promiseSpawn 中会将 cwd 传入来获取 uid 和 gid。而在我们线上服务的容器里，我们是在 /home/web_server/project 下执行 npm start，该目录所属用户是 web_server，用户组是 web_server。所以 npm 在启动子进程时“切换”了用户。

所以实际情况是，pm2 start ecosystemt.config.js 相当于是被 web_server 用户启动的，但是环境变量 $HOME 仍然是 /root。所以在 /root 中创建文件夹，自然就没有权限。

3.2、v6.x 中 npm script 实现方式的区别

以下代码来自 npm/cli v6.14.8

v7.x 为了权限安全，做了上述操作，那么 v6.x 如何呢？

v6.x 的 npm script 入口是 lib/run-script.js 文件：

1
2
3
4
5
6
7
8
9
10
11
12

function run (pkg, wd, cmd, args, cb) {
  // ...
  chain(cmds.map(function (c) {
    // pass cli arguments after -- to script.
    if (pkg.scripts[c] && c === cmd) {
      pkg.scripts[c] = pkg.scripts[c] + joinArgs(args)
    }

    // when running scripts explicitly, assume that they're trusted.
    return [lifecycle, pkg, c, wd, { unsafePerm: true }]
  }), cb)
}

而其实际执行则需要从 lifecycle 方法中来找。上面这段代码的最后一行还有一个非常重要的参数 { unsafePerm: true }，之后会用到。

lifecycle 本身代码并不复杂，主要就是参数调整，然后调用实际函数。和 uid、gid 实际的设置代码是在 npm-lifecycle/index.js 中的 runCmd 里：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

function runCmd (note, cmd, pkg, env, stage, wd, opts, cb) {
  // ...
  var unsafe = opts.unsafePerm
  var user = unsafe ? null : opts.user
  var group = unsafe ? null : opts.group
  
  // ...
  if (unsafe) {
    runCmd_(cmd, pkg, env, wd, opts, stage, unsafe, 0, 0, cb)
  } else {
    uidNumber(user, group, function (er, uid, gid) {
      if (er) {
        er.code = 'EUIDLOOKUP'
        opts.log.resume()
        process.nextTick(dequeue)
        return cb(er)
      }
      runCmd_(cmd, pkg, env, wd, opts, stage, unsafe, uid, gid, cb)
    })
  }
}

// ...
function runCmd_ (cmd, pkg, env, wd, opts, stage, unsafe, uid, gid, cb_) {
  // ...
  var proc = spawn(sh, args, conf, opts.log)
  // ...
}

runCmd 里会通过传入的 opt.unsafePem 参数（就是上面设置的那个 { unsafePerm: true }）来判断是否是 unsafe 的。如果是 unsafe，则会在调用 runCmd_ 时将 uid、gid 设置为 0。0 就代表 root 用户和 root 用户组。

而最终在 runCmd_ 中的 spawn 就是 child_process 中的 spawn 方法：

1
2
3
4
5
6
7

const _spawn = require('child_process').spawn
// ...
function spawn (cmd, args, options, log) {
  // ...
  const raw = _spawn(cmd, args, options)
  // ...
}

到这里我们就定位到了该问题：

• 在 v6.x 中，只要没有设置 unsafe-pem 这个 npm config，npm script 就会在启动子进程时默认设置为 root。
• 而在 v7.x 中，如果运行时是 root 用户，则会根据 cwd 所属的用户/用户组，来设置启动子进程的 uid 和 gid。

目前从代码实现来看，似乎没有特别好的处理方式，比较简答的两种就是：

• 如果用 v7.x，在我们这个场景下，可以把 /home/web_server/project 所属用户/用户组改为 root。但权限的改动可能会引发其他问题。
• 先暂时回退到 v6.x，使环境和保持一致。

3.3、npm cli 的变更日志

其实，这个变更在 npm v7.0.0-beta.0 发布时的 CHANGELOG 里是有提到的。不过只有寥寥一行：

The user, group, uid, gid, and unsafe-perms configurations are no longer relevant. When npm is run as root, scripts are always run with the effective uid and gid of the working directory owner.

大致说的就是咱们上面从代码分析的结论：如果是 root 运行 npm，则在脚本执行时切换到当前工作目录的 owner。

然后如果你跟着代码看下来，也会发现 v6.x 中的 unsafe-pem 配置，在 v7.0.0 开始就被废弃了。不过 npm cli 文档更新的较慢，直到 v7.0.0 正式版发布后的一个月后，才在 v7.0.15 的 Release 里把 unsafe-pem 从文档中移除。

3.4、其他可能出现的问题

这个功能实现的变更，除了会导致一些文件操作时的权限问题，还会有一些其他场景的权限错误。例如在如果你用 npm script 启动一个 nodejs server，要绑定 443 端口，这个时候可能就会报错。因为会需要 root 权限来执行这个端口绑定。在 issue 里就有人提到了这个情况。

4、加餐：child_process#spawn 是如何设置 user 和 group 的？

通过上面的分析，问题已经被解决了。沿着这个问题，可以具体看了下 Nodejs 中，child_process 模块的 spawn 方法是如何设置 user 和 group 的。

以下代码基于 Nodejs v14.16.1。只关注 unix 实现。

Nodejs 中，我们在上层引入的模块，是直接放在 lib 下面的，而其一般会在调用 lib/internal 下的对应模块，这部分会直接使用 internalBinding 来调用 C++ 对象和方法。child_process 也不例外，你会在 lib/internal/child_process.js 中看到如下代码：

1
2
3
4

ChildProcess.prototype.spawn = function(options) {
  // ...
  const err = this._handle.spawn(options);
  // ...

因为比较简答，所以这里省去了 lib/child_process.js 中的方法。只要知道，我们在 JavaScript 层使用 spawn 方法时，最后会调用到 ChildProcess 实例的 spawn 方法即可。可以看到最后是调用了 this._handle.spawn。那么 this._handle 是什么呢？

它其实就是通过 binding 创建的 Process 对象：

1
2
3
4
5
6
7
8
9
10

const { Process } = internalBinding('process_wrap');

// ...
function ChildProcess() {
  EventEmitter.call(this);

  // ...
  this._handle = new Process();
  // ...
}

这个 binding 的设置在 src/process_wrap.cc 中，

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

  static void Spawn(const FunctionCallbackInfo%&-l-t%Value%&-g-t%& args) {
    // ...

    // options.uid
    Local%&-l-t%Value%&-g-t% uid_v =
        js_options-%&-g-t%Get(context, env-%&-g-t%uid_string()).ToLocalChecked();
    if (!uid_v-%&-g-t%IsUndefined() && !uid_v-%&-g-t%IsNull()) {
      CHECK(uid_v-%&-g-t%IsInt32());
      const int32_t uid = uid_v.As%&-l-t%Int32%&-g-t%()-%&-g-t%Value();
      options.flags |= UV_PROCESS_SETUID;
      options.uid = static_cast%&-l-t%uv_uid_t%&-g-t%(uid);
    }

    // options.gid
    Local%&-l-t%Value%&-g-t% gid_v =
        js_options-%&-g-t%Get(context, env-%&-g-t%gid_string()).ToLocalChecked();
    if (!gid_v-%&-g-t%IsUndefined() && !gid_v-%&-g-t%IsNull()) {
      CHECK(gid_v-%&-g-t%IsInt32());
      const int32_t gid = gid_v.As%&-l-t%Int32%&-g-t%()-%&-g-t%Value();
      options.flags |= UV_PROCESS_SETGID;
      options.gid = static_cast%&-l-t%uv_gid_t%&-g-t%(gid);
    }
    
    int err = uv_spawn(env-%&-g-t%event_loop(), &wrap-%&-g-t%process_, &options);
    wrap-%&-g-t%MarkAsInitialized();
    
    // ...
}

可以看到，它把从 JavaScript 层设置的 uid 和 gid 设置到 options 上，然后调用了 uv_spawn 函数创建子进程。在 uv_spawn 中对于创建的子进程会通过 uv__process_child_init 来做初始化设置：

1
2
3
4
5
6
7
8
9
10
11

int uv_spawn(uv_loop_t* loop,
             uv_process_t* process,
             const uv_process_options_t* options) {

    // ...
    if (pid == 0) {
        uv__process_child_init(options, stdio_count, pipes, signal_pipe[1]);
        abort();
    }
    // ...
}

最后则是在 uv__process_child_init 里通过 setuid 和 setgid 这两个系统调用来实现的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

static void uv__process_child_init(const uv_process_options_t* options,
                                   int stdio_count,
                                   int (*pipes)[2],
                                   int error_fd) {
    // ...
    if ((options-%&-g-t%flags & UV_PROCESS_SETGID) && setgid(options-%&-g-t%gid)) {
        uv__write_int(error_fd, UV__ERR(errno));
        _exit(127);
    }

    if ((options-%&-g-t%flags & UV_PROCESS_SETUID) && setuid(options-%&-g-t%uid)) {
        uv__write_int(error_fd, UV__ERR(errno));
        _exit(127);
    }
    // ...
}

在 Nodejs 官方文档中也有介绍。

我们通过阅读代码也印证了这一点。

完。

本文记录了使用 Node gRPC（static codegen 方式）时，遇到的一个“奇怪”的坑。虽然问题本身并不常见，但顺着问题排查发现其中涉及到了一些有意思的点。去沿着问题追根究底、增长经验是一种不错的学习方式。所以我把这次排查的过程以及涉及到的点记录了下来。

为了让大家在阅读时有更好的体验，我准备了一个 demo 来还原该问题，感兴趣的朋友可以 clone 下来，配合文章一起“食用”。

1、场景还原

如果在你了解过或在 NodeJS 中使用过 gRPC，那么一定会知道它有两种使用模式 ——「动态代码生成」（dynamic codegen）和「静态代码生成」（static codegen）。

这里简单解释下（对 gRPC 有了解的小伙伴可以直接跳过这段）。RPC 框架一般都会选择一种 IDL，而 gRPC 默认使用的就是 protocol bufffers，我们一般会叫该文件 PB 或 proto 文件。根据 PB 文件可以自动生成序列化/反序列化代码（_xxx_pb.js_），用于 gRPC 时还会生成适配 gRPC 的代码（_xxx_grpc_pb.js_`）。如果在 Nodejs 进程启动后，再 load PB 文件生成对应方法，叫做「动态代码生成」；而先用工具生成出对应的 js 文件，运行时直接 require 生成的 js 则叫作「静态代码生成」。可以参见 gRPC 官方库中提供的示例。

我们的项目使用了公司内部的解密组件包（也是我们维护的），叫 keycenter。解密组件中需要用到 gRPC 请求，并且它使用了「静态代码生成」这种模式。

之前项目一直都正常运行。直到有一天引入了 redis 组件来实现缓存功能。在满心欢喜地加完代码运行后，控制台报出了如下错误信息：

1
2
3
4
5
6
7

Error: 13 INTERNAL: Request message serialization failure: Expected argument of type keycenter.SecretData
    at Object.callErrorFromStatus (/Users/xxxx/server/node_modules/@infra-node/grpc-js/build/src/call.js:31:26)
    at Object.onReceiveStatus (/Users/xxxx/server/node_modules/@infra-node/grpc-js/build/src/client.js:176:52)
    at Object.onReceiveStatus (/Users/xxxx/server/node_modules/@infra-node/grpc-js/build/src/client-interceptors.js:342:141)
    at Object.onReceiveStatus (/Users/xxxx/server/node_modules/@infra-node/grpc-js/build/src/client-interceptors.js:305:181)
    at /Users/zhouhongxuan/programming/xxxx/server/node_modules/@infra-node/grpc-js/build/src/call-stream.js:124:78
    at processTicksAndRejections (internal/process/task_queues.js:75:11)

而这个 redis 组件确实间接依赖了 gRPC。这里放一个组件模块依赖关系，说明一下项目使用的各组件包之间的关系。

其中每个黄色组件就是一单独的 npm 包。业务代码直接使用了 keycenter 包进行了秘钥的解密；同时引入了 redis 缓存组件，而缓存模块间接依赖了 keycenter。最终 keycenter 组件通过「静态代码生成」的方式使用 gRPC。

下面我们就来一起看看这个问题。

2、问题排查

❗️ 以下的章节顺序并非是排查时的实际顺序。大家实际排查问题时，还是建议先看“最近的现场”。 👀 例如这个问题，就会首先去 Request message serialization failure 抛错的地方查看情况。同时再辅以上层（外层）逻辑的排查，两头夹逼找到真相。但为了让文章阅读起来更顺畅，能够有从问题表象一步步走近真相，所以选择了目前的文章结构。我会尝试去尽量保留实际的排查路径。

2.1、莫非是 redis 组件内部逻辑出错了？

最直接的想法就是：新引入的这个 redis 组件有问题。因为出现问题的第一时间，我就把项目里下面这行代码注释掉了：

1
2

- this.redis = new Redis(redisConfig);
+ // this.redis = new Redis(redisConfig);

注释完果然就好了。所以引入新组件确实导致了问题。

由于报错和 gRPC 有关，而 redis 内部也间接依赖到了 gRPC（因为间接依赖了 keycenter），那么我的第一反应就是，这个组件内部逻辑可能有问题。也许是哪步操作使用到了 keycenter 方法，然后报出了错误。

但这个想法出现的有多快，排除的就有多快。

通过添加断点、日志的方式，很快就得出了一个结论：redis 组件虽然依赖到了 keycenter，但是整个实例化过程中完全不会调用它的方法，既然没有调用，这个 gRPC 的错误自然不是它直接导致的。

但它和 redis 组件或多或少脱不了关系。

2.2、是否真的是 redis 实例化导致了报错？

上面我通过注释掉 Redis 实例化的代码行后运行正常，初步判断是实例化导致的问题。然而我忽略了重要的一点，typescript 编译时，对于 import 但是没有使用的模块，在产出的代码里是会把模块引入的这段删除的。

例如下面这段代码，导入的模块实际没有使用，在编译产出的代码中就不会导入该模块：

1
2

import Redis from '@infra-node/redis';
export default 1;

而如果是这样

1
2

import Redis from '@infra-node/redis';
Redis;

或者这样

1

import '@infra-node/redis';

则模块引入的代码 require(@infra-node/redis) 在产出中会被保留。因此，实例化操作很可能并不是导致问题的原因。

通过进一步测试，发现直接原因是引入了 @infra-node/redis 模块。导入模块就会导致问题，只要不导入就没事儿，我第一时间的直觉有两个：

• 副作用
• 依赖关系

到这里，我们先回到最初的问题。

2.3、new A instanceof A === false?

还记得最初的问题么？问题的抛错 Error: 13 INTERNAL: Request message serialization failure: Expected argument of type XXX 来自于 grpc-tools 生成的 Nodejs 版 xxx_grpc_pb.js 代码：

1
2
3
4
5
6

function serialize_keycenter_SecretData(arg) {
  if (!(arg instanceof keycenter_pb.SecretData)) {
    throw new Error('Expected argument of type keycenter.SecretData');
  }
  return Buffer.from(arg.serializeBinary());
}

serialize_keycenter_SecretData 是用于在请求时将 SecretData 实例序列化为二进制数据的方法。可以看到，方法里会判断 arg 是否是 keycenter_pb.SecretData 的实例。

在我们项目的场景下，我们事先会得到了 pb 对象二进制的 base64 编码值，所以在代码中会使用 xxx_pb.js 文件提供的反序列化生成 SecretData 的实例，并设置其他属性。

1
2
3
4
5
6
7
8
9
10

import { SecretData } from '../gen/keycenter_pb';
// ...

// 反序列化二进制
const secretData = SecretData.deserializeBinary(Buffer.from(base64, 'base64'));
secretData.setKeyName(keyName);

keyCenter.decrypt(secretData, metadata, (err, res) =%&-g-t% {
    // ...
});

并且这里我打印 arg 后，在控制台看起来它的值也很正常。

SecretData.deserializeBinary 的方法实现如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

proto.keycenter.SecretData.deserializeBinary = function(bytes) {
  var reader = new jspb.BinaryReader(bytes);
  var msg = new proto.keycenter.SecretData;
  return proto.keycenter.SecretData.deserializeBinaryFromReader(msg, reader);
};

proto.keycenter.SecretData.deserializeBinaryFromReader = function(msg, reader) {
  while (reader.nextField()) {
    if (reader.isEndGroup()) {
      break;
    }
    var field = reader.getFieldNumber();
    switch (field) {
    case 1:
      var value = /** @type {string} */ (reader.readString());
      msg.setKeyName(value);
      break;
    case 2:
      ...
    }
  }
  return msg;
};

从 var msg = new proto.keycenter.SecretData; 看起其就是通过 SecretData 构造函数创建了一个实例，并传入 .deserializeBinaryFromReader 方法中进行赋值，最后返回该实例。

所以目前从这个错误看起来，像是一个 new A instanceof A === false 的伪命题。但显然并不可能。所以我的判断是，这里面一定有一个“李鬼” —— 有一个看起来像是 SecretData 但实际不是的家伙冒充了它。

听起来似乎很奇怪。只能揣着性子继续排查。

2.4、“奇怪”的依赖安装？

首先回顾一下上面列出的包/模块依赖关系：

我瞟了下目前实际的包安装情况。大致如下（省略了一些无关的包信息）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

.
├── grpc-js
│   ...
├── keycenter
└── redis
    ├── Changelog.md
    ├── LICENSE
    ├── README.md
    ├── built
    ├── node_modules
    │   ├── @infra-node
    │   │   │ ...
    │   │   └── keycenter
    │   ├── chokidar
    │   ├── debug
    │   ├── p-map
    │   └── readdirp
    └── package.json

上面列出了目前项目中的包安装情况。可以看到一个比较有意思的地方：外层存在一个 keycenter 包，同时在 redis 内部也安装了一个 keycenter 包。这是为什么呢？

原因很简单：项目直接依赖的 keycenter 版本声明与 redis 中的依赖版本无法合并指向同一版本，所以会在两个地方分别安装。这是 npm 的正常机制。一般这种情况也并不会出现问题。

但当我手动删除了 redis 中的 keycenter 后，项目又可以正常运行了。看来“李鬼”就是这儿了。

2.5、莫非引用了错误的模块文件？

结合上面的情况，对于 new A instanceof A === false 的问题，基本可以认定为是 new A' instanceof A === false（注意里面的 A 和 A’）。也就是在

1
2
3
4
5
6

function serialize_keycenter_SecretData(arg) {
  if (!(arg instanceof keycenter_pb.SecretData)) {
    throw new Error('Expected argument of type keycenter.SecretData');
  }
  return Buffer.from(arg.serializeBinary());
}

这个方法执行时，传入的 arg 的构造函数与方法中的 keycenter_pb.SecretData 实际不同。这让我怀疑，是不是引用了错误的 _pb.js 文件。例如一个是用的外层 keycenter 中的 keycenter_pb.js，另一个则是使用到了 redis 中 keycenter 中的 keycenter_pb.js。两个文件一模一样，函数签名一模一样，但看起相同的两个对象，实则不同，自然过不了判断。

难道是构造 arg 参数时引入的 keycenter_pb.js 和 serialize_keycenter_SecretData 方法引入的 keycenter_pb.js 不同么？

基于我对 Nodejs require 机制的了解，基本排除了这个可能。它们是通过相对路径引入，根据模块寻路的规则，都会命中各自包内的代码模块。不存在引到其他包内的代码文件的情况。

2.6、模块是如何被“污染”的？

如果引用的模块没有问题，那么会不会是模块内的变量被“污染”了？

这就和我最开始的直觉 —— “副作用”，有些关联了。副作用的产生场景很多，但是有一个场景非常典型，就是全局变量的使用。在查看 keycenter_pb.js 文件的代码后，我发现果然如此：

1
2
3
4
5
6
7

var jspb = require('google-protobuf');
var goog = jspb;
var global = Function('return this')();
// ...
goog.exportSymbol('proto.keycenter.SecretData', null, global);
// ...
goog.object.extend(exports, proto.keycenter);

代码通过 Function('return this')() 获取了全局对象。然后通过执行 goog.exportSymbol 方法，在全局对象上挂载 global.proto.keycenter.SecretData 属性值。最后再在 exports 上挂载 proto.keycenter 对象作为导出。

但如果仔细分析，仅仅上述代码，并不会导致这个错误。因为它会先修改 global 引用的指向，再修改 global 上对应的对象。例如引入模块后引用关系大致如下：

当运行环境中再次引入一个同样内容 _pb'.js 文件后，就会变成如下引用关系。

可以看到原先的 proto 对象并不会被修改，即外部之前导入的对象并不会变。那么究竟是如何被“污染”的呢？

其实问题来自于 2.3 节中用到的 .deserializeBinary 这个方法。这是 _pb.js 在构造函数上暴露出来的静态方法，可以根据二进制数据生成对应的实例对象：

1
2
3
4
5

proto.keycenter.SecretData.deserializeBinary = function(bytes) {
    var reader = new jspb.BinaryReader(bytes);
    var msg = new proto.keycenter.SecretData;
    return proto.keycenter.SecretData.deserializeBinaryFromReader(msg, reader);
};

注意第二行 var msg = new proto.keycenter.SecretData，使用了 proto.keycenter.SecretData 这个构造函数，而我们根据前面的代码可以知道，这里的 proto 其实是 [global].proto。所以一旦我们的全局对象上的指向被修改后，这里使用的 keycenter.SecretData 其实就是另一个构造函数了。

真相大白。导致错误的过程如下：

1. 首先 keycenter_grpc_pb.js 引入了同目录下 keycenter_pb.js 文件，模块中的 keycenter.SecretData 构造函数这时候就确定了
2. 因为一些其他原因，某个包引用了另一个地方的、内容相同的 pb 文件，为了区分我们叫它 keycenter_pb-2.js。它和 keycenter_pb.js 内容一摸一样，不过是两个文件。这时候 global 上指向的对象就被修改了
3. 然后导入 keycenter_pb.js 模块，再使用 SecretData.deserializeBinary 生成实例，传入 keycenter_grpc_pb.js 中的方法就会出错了

✨ 为了大家更好理解，我复刻了这个问题的核心逻辑，做成了 demo，大家可以 clone 到本地再配合文章内容来查看、运行。

☕️ 上面已经完成了问题的排查，下面的文章会进入到另一个主题 —— 问题修复。本身以为会较为顺畅的修复过程，也遇到一些意料之外的问题。

3、解决思路

如果理解了错误原因，就会发现这个错误出现的条件还是比较苛刻的。需要同时满足以下几个必要条件才会复现：

1. 进行了挂载全局变量的操作
2. 项目同时 import 两个内容相同的 _pb.js 文件
3. 使用了 .deserializeBinary 方法来创建实例对象
4. 模块的 import 顺序需要先导入 _grpc_pb.js，再导入 _pb'.js（同内容的另一个 pb 文件）

针对 2～4 这三个条件，我们只要破坏其一，就可以避免问题发生。我在 demo 项目中分别写了对应的代码（correct-2.ts、correct-3.ts、correct-4.ts），感兴趣的话可以试下。

如果作为包提供方，要解决这个问题虽然看似方式很多，但是现实上我们能控制的有限 ——

• 先是第 2 条，会需要保证只安装一个 keycenter 包。不同包、模块对于包的版本依赖是外部控制的，不受包自身控制，因此很难确保根除；
• 然后是第 3 条，使用 .deserializeBinary 是功能要求，如果要规避这个方法的坑会使代码变得较为 tricky；
• 最后是第 4 条，引用顺序显然也是外部控制的，不受包自身所控

所以我们尽量还是希望能找一个“正规”的路子，使得通过 grpc-tools 或者 protoc 生成的 _pb.js 文件，不会产生全局污染（也就是破除条件 1）。

4、修复之路

4.1、让 protoc 生成的代码避免全局污染

按上面的思路，我们会希望在 protoc 生成时就产出一份“安全”的 _pb.js 静态文件。

protoc 支持在 js_out 参数中设置 import_style 来控制模块类型。官方文档里提供了 commonjs 这个参数。

1

protoc --proto_path=src --js_out=import_style=commonjs,binary:build/gen src/foo.proto src/bar/baz.proto

但是遗憾的是，这个参数并不会生成我们预想的代码，它生成的代码就是我们在上文中看到的“问题代码”。所以还有其他 import_style 么？

文档里没有，只能去源码里找答案了。

下面会涉及到 protoc，这里简单介绍了一下，便于不了解的朋友能快速理解。protobuf 这个仓库中包含了 Protocol Compiler。其中各个语言相关的代码生成器放在了 src/google/protobuf/compiler/ 下面对应名称的文件夹里。例如 JavaScript 就是 /js 文件夹内。

在源码中可以发现，其支持的 style 值并非只有 commonjs 和 closure 两种：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// ...
else if (options[i].first == "import_style") {
  if (options[i].second == "closure") {
    import_style = kImportClosure;
  } else if (options[i].second == "commonjs") {
    import_style = kImportCommonJs;
  } else if (options[i].second == "commonjs_strict") {
    import_style = kImportCommonJsStrict;
  } else if (options[i].second == "browser") {
    import_style = kImportBrowser;
  } else if (options[i].second == "es6") {
    import_style = kImportEs6;
  } else {
    *error = "Unknown import style " + options[i].second + ", expected " +
              "one of: closure, commonjs, browser, es6.";
  }
}
// ...

但大致浏览完源码后，我发现 browser 和 es6 两种 style 实际也不能满足我们的需求。这时候就剩下 commonjs_strict 了。这个 strict 感觉就会非常贴合我们的目标。

主要的相关代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// Generate "require" statements.
if ((options.import_style == GeneratorOptions::kImportCommonJs ||
      options.import_style == GeneratorOptions::kImportCommonJsStrict)) {
  printer-%&-g-t%Print("var jspb = require('google-protobuf');\n");
  printer-%&-g-t%Print("var goog = jspb;\n");

  // Do not use global scope in strict mode
  if (options.import_style == GeneratorOptions::kImportCommonJsStrict) {
    printer-%&-g-t%Print("var proto = {};\n\n");
  } else {
    printer-%&-g-t%Print("var global = Function('return this')();\n\n");
  }
  // ...
}

这里就可以看出 commonjs_strict 和 commonjs 最大的区别就是是否使用了全局变量。如果是 commonjs_strict 则会使用 var proto = {}; 来代替全局变量。完全满足需求！

但是，实际使用后，我发现了另一个问题。

4.2、grpc-tools 并不适配 commonjs_strict

import_style=commonjs_strict 另一个最大的区别在于导出代码的生成：

1
2
3
4
5
6
7
8
9

// if provided is empty, do not export anything
if (options.import_style == GeneratorOptions::kImportCommonJs &&
    !provided.empty()) {
  printer-%&-g-t%Print("goog.object.extend(exports, $package$);\n", "package",
                  GetNamespace(options, file));
} else if (options.import_style == GeneratorOptions::kImportCommonJsStrict) {
  printer-%&-g-t%Print("goog.object.extend(exports, proto);\n", "package",
                  GetNamespace(options, file));
}

这样看可能不太直观，直接贴两种 style 生成的代码就很明白了。

下面是用 commonjs_strict 生成的：

1

goog.object.extend(exports, proto);

下面是用 commonjs 生成的：

1

goog.object.extend(exports, proto.keycenter);

这样就能明显看出区别了。commonjs 形式导出时会导出 package 下的对象。因此，在我们使用对应的 _pb.js 文件时，会需要调整一下导入的代码。此外，grpc-tools 生成的 _grpc_pd.js 静态代码因为也会导入 _pb.js 文件，因此也需要适配这种导出。

这里简单介绍下 grpc-tools 的角色。它做了两件事，一个是 wrap 了一些 protoc 命令行，这样用户可以直接使用 grpc-tools 而不去关心 protoc；另一个是实现了一个 protoc 的 grpc 插件。关于 protoc 插件机制与如何实现一个 protoc 插件，后续有机会可以单写篇文章介绍。

而当我满心欢喜地去翻阅 grpc-tools 源码时发现，

1
2
3
4

grpc::string file_path =
    GetRelativePath(file-%&-g-t%name(), GetJSMessageFilename(file-%&-g-t%name()));
out-%&-g-t%Print("var $module_alias$ = require('$file_path$');\n", "module_alias",
            ModuleAlias(file-%&-g-t%name()), "file_path", file_path);

它并不会考虑 import_style=commonjs_strict 这种情况，而是固定生成对应 commonjs 的导入代码。也有 issue 提到了这个问题。

4.3、只能自己动手了

好吧，这个导入/导出的问题目前没有特别好的解决办法。

我们这边之前因为一些特殊需求，所以 folk 了 grpc-tools 的代码，修改了内部实现以适配我们的 RPC 框架。因此这块就自己上手，支持了 import_style=commonjs_strict 这种情况，修改了导入时的代码：

1
2
3
4
5
6
7
8

grpc::string pb_package = file-%&-g-t%package();
if (params.commonjs_strict && !pb_package.empty()) {
  out-%&-g-t%Print("var $module_alias$ = require('$file_path$').$pb_package$;\n", "module_alias",
           ModuleAlias(file-%&-g-t%name()), "file_path", file_path, "pb_package", pb_package);
} else {
  out-%&-g-t%Print("var $module_alias$ = require('$file_path$');\n", "module_alias",
           ModuleAlias(file-%&-g-t%name()), "file_path", file_path);
}

当然还需要配合做一些其他改动，例如 CLI 入参的判断处理等，这里就不贴了。

当然，令人头疼的问题不止这一个，如果你使用了其他 protoc 插件自动生成 .d.ts 文件的话，这块也会需要适配 import_style=commonjs_strict 的情况。

4.4、其他方式

当然，还有一种解决方法就是不用使用 static codegen，而是使用 proto-loader 来做 dynamic codegen。这样就规避了这个问题。

5、最后

本文主要记录了一次 gRPC 相关报错的排查过程。包括找出原因、提出解决思路到最后修复的整个过程。

排查问题是每个工程师经常会面对的事儿，也常常充满挑战。往往这些问题的落脚处可能并不大，修复工作也只是简单几行代码。而排障的过程，伴随着各类知识或技术点的使用，从表象到真相，整个过程也是工程师独有的乐趣。

而在文章写作上，相比介绍一个技术点，要写好一篇排障文章往往更不容易，所以也想挑战一下自己。

文章内容有一个配套的 demo 代码，可以用来配合理解文章中的问题。

两周前（202.02.17），vite2.0 发布了，作为使用了浏览器原生 ESM 为下一代前端工具，vite 2.0 相较于 1.0 更加成熟。在此之前笔者就开始关注这类「新型」的前端工具。这次趁着 vite 2.0 发布，也成功将一个基于 vue-cli(-service) + vue2 的已有项目进行了迁移。

迁移工作比较顺利，花了不到半天时间。但整个迁移过程中也遇到了一些小问题，这里汇总一下，也方便遇到类似问题的朋友一起交流和参考。

项目背景

在介绍具体迁移工作前，先简单介绍下项目情况。目前该项目上线不到一年，不太有构建相关的历史遗留债务。项目包含 1897 个模块文件（包括 node_modules 中模块），使用了 vue2 + vuex + typescript 的技术栈，构建工具使用的是 vue-cli（webpack）。算是一套比较标准的 vue 技术栈。由于是内部系统，项目对兼容性的要求较低，用户基本都使用较新的 Chrome 浏览器（少部分使用 Safari）。

迁移工作

下面具体来说下迁移中都做了哪些处理。

1、配置文件

首先需要安装 vite 并创建 vite 的配置文件。

1

npm i -D vite

vue-cli-service 中使用 vue.config.js 作为配置文件；而 vite 则默认会需要创建一个 vite.config.ts 来作为配置文件。基础的配置文件很简单：

1
2
3
4
5
6
7

import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    // ...
  ],
})

创建该配置文件，之前的 vue.config.js 就不再使用了。

2、入口与 HTML 文件

在 vite 中也需要指定入口文件。但和 webpack 不同，在 vite 中不是指定 js/ts 作为入口，而是指定实际的 HTML 文件作为入口。

在 webpack 中，用户通过将 entry 设置为入口 js（例如 src/app.js）来指定 js 打包的入口文件，辅以 HtmlWebpackPlugin 将生成的 js 文件路径注入到 HTML 中。而 vite 直接使用 HTML 文件，它会解析 HTML 中的 script 标签来找到入口的 js 文件。

因此，我们在入口 HTML 中加入对 js/ts 文件的 script 标签引用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

%&-l-t%!DOCTYPE html%&-g-t%
%&-l-t%html lang="en"%&-g-t%

%&-l-t%head%&-g-t%
  %&-l-t%meta charset="utf-8"%&-g-t%
  %&-l-t%meta http-equiv="X-UA-Compatible" content="IE=edge"%&-g-t%
  %&-l-t%meta name="viewport" content="width=device-width,initial-scale=1.0"%&-g-t%
  %&-l-t%title%&-g-t%%&-l-t%%= htmlWebpackPlugin.options.title %%&-g-t%%&-l-t%/title%&-g-t%
%&-l-t%/head%&-g-t%

%&-l-t%body%&-g-t%
  %&-l-t%noscript%&-g-t%
    We're sorry but %&-l-t%%= htmlWebpackPlugin.options.title %%&-g-t% doesn't work properly without JavaScript enabled.
  %&-l-t%/noscript%&-g-t%
  %&-l-t%div id="app"%&-g-t%%&-l-t%/div%&-g-t%
+ %&-l-t%script type="module" src="/src/main.ts"%&-g-t%%&-l-t%/script%&-g-t%
%&-l-t%/body%&-g-t%

%&-l-t%/html%&-g-t%

注意上面 %&-l-t%script type="module" src="/src/main.ts"%&-g-t%%&-l-t%/script%&-g-t% 这一行，它使用浏览器原生的 ESM 来加载该脚本，/src/main.ts 就是入口 js 的源码位置。在 vite dev 模式启动时，它其实启动了一个类似静态服务器的 server，将 serve 源码目录，因此不需要像 webpack 那样的复杂模块打包过程。模块的依赖加载将完全依托于浏览器中对 import 语法的处理，因此可以看到很长一串的脚本加载瀑布流：

这里还需要注意 project root 的设置。在默认是 process.cwd()，而 index.html 也会在 project root 下进行寻找。为了方便我将 ./public/index.html 移到了 ./index.html。

3、使用 vue 插件

vite 2.0 提供了对 vue 项目的良好支持，但其本身并不和 vue 进行较强耦合，因此通过插件的形式来支持对 vue 技术栈的项目进行构建。vite 2.0 官网目前（2021.2.28）推荐的 vue 插件会和 vue3 的 SFC 一起使用更好。因此这里使用了一个专门用来支持 vue2 的插件 vite-plugin-vue2，支持 JSX，同时目前最新版本也是支持 vite2 的。

使用上也很简单：

1
2
3
4
5
6
7
8

import { defineConfig } from 'vite';
+ import { createVuePlugin } from 'vite-plugin-vue2';

export default defineConfig({
  plugins: [
+   createVuePlugin(),
  ],
});

4、处理 typescript 路径映射

使用 vite 构建 ts 项目时，如果使用了 typescript 路径映射的功能，就需要进行特殊处理，否则会出现模块无法解析（找不到）的错误：

这里需要使用 vite-tsconfig-paths 这个插件来做路径映射的解析替换。其原理较为简单，大致就是 vite 插件的 resolveId 钩子阶段，利用 tsconfig-paths 这个库来将路径映射解析为实际映射返回。有兴趣的可以看下该插件的实现，比较简短。

具体使用方式如下：

1
2
3
4
5
6
7
8
9
10
11

import { defineConfig } from 'vite';
import { createVuePlugin } from 'vite-plugin-vue2';
+ import tsconfigPaths from 'vite-tsconfig-paths';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    createVuePlugin(),
+   tsconfigPaths(),
  ],
});

5、替换 CommonJS

vite 使用 ESM 作为模块化方案，因此不支持使用 require 方式来导入模块。否则在运行时会报 Uncaught ReferenceError: require is not defined 的错误（浏览器并不支持 CJS，自然没有 require 方法注入）。

此外，也可能会遇到 ESM 和 CJS 的兼容问题。当然这并不是 vite 构建所导致的问题，但需要注意这一点。简单来说就是 ESM 有 default 这个概念，而 CJS 没有。任何导出的变量在 CJS 看来都是 module.exports 这个对象上的属性，ESM 的 default 导出也只是 cjs 上的 module.exports.default 属性而已。例如在 typescript 中我们会通过 esModuleInterop 配置来让 tsc 添加一些兼容代码帮助解析导入的模块，webpack 中也有类似操作。

例如之前的代码：

1
2
3
4

module.exports = {
    SSO_LOGIN_URL: 'https://xxx.yyy.com',
    SSO_LOGOUT_URL: 'https://xxx.yyy.com/cas/logout',
}

1

const config = require('./config');

在导出和导入上都需要修改为 ESM，例如：

1
2
3
4

export default {
    SSO_LOGIN_URL: 'https://xxx.yyy.com',
    SSO_LOGOUT_URL: 'https://xxx.yyy.com/cas/logout',
}

1

import config from './config';

6、环境变量的使用方式

使用 vue-cli（webpack）时我们经常会利用环境变量来做运行时的代码判断，例如：

1
2
3

const REPORTER_HOST = process.env.REPORTER_TYPE === 'mock'
  ? 'http://mock-report.xxx.com'
  : 'http://report.xxx.com';

vite 仍然支持环境变量的使用，但不再提供 process.env 这样的访问方式。而是需要通过 import.meta.env 来访问环境变量：

1
2
3
4

-const REPORTER_HOST = process.env.REPORTER_TYPE === 'mock'
+const REPORTER_HOST = import.meta.env.REPORTER_TYPE === 'mock'
  ? 'http://mock-report.xxx.com'
  : 'http://report.xxx.com';

与 webpack 类似，vite 也内置了一些环境变量，可以直接使用。

7、import.meta.env types

补充：vite 提供了它所需要的 types 定义，可以直接应用 vite/client 来引入，可以不需要通过以下方式来自己添加。

如果在 typescript 中通过 import.meta.env 来访问环境变量，可能会有一个 ts 错误提示：类型“ImportMeta”上不存在属性“env”。

这是因为在目前版本下（v4.2.2）import.meta 的定义还是一个空的 interface：

1
2

interface ImportMeta {
}

但我们可以通过 interface 的 merge 能力，在项目中进一步定义 ImportMeta 的类型来拓展对 import.meta.env 的类型支持。例如之前通过 vue-cli 生成的 ts 项目在 src 目录下会生成 vue-shims.d.ts 文件，可以在这里拓展 env 类型的支持：

1
2
3
4
5

declare global {
  interface ImportMeta {
    env: Record%&-l-t%string, unknown%&-g-t%;
  }
}

这样就不会报错了。

8、webpack require context

在 webpack 中我们可以通过 require.context 方法「动态」解析模块。比较常用的一个做法就是指定某个目录，通过正则匹配等方式加载某些模块，这样在后续增加新的模块后，可以起到「动态自动导入」的效果。

例如在项目中，我们动态匹配 modules 文件夹下的 route.ts 文件，在全局的 vue-router 中设置 router 配置：

1
2
3
4
5
6
7

const routes = require.context('./modules', true, /([\w\d-]+)\/routes\.ts/)
    .keys()
    .map(id =%&-g-t% context(id))
    .map(mod =%&-g-t% mod.__esModule ? mod.default : mod)
    .reduce((pre, list) =%&-g-t% [...pre, ...list], []);

export default new VueRouter({ routes });

文件结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

src/modules
├── admin
│   ├── pages
│   └── routes.ts
├── alert
│   ├── components
│   ├── pages
│   ├── routes.ts
│   ├── store.ts
│   └── utils
├── environment
│   ├── store
│   ├── types
│   └── utils
└── service
    ├── assets
    ├── pages
    ├── routes.ts
    ├── store
    └── types

require context 是 webpack 提供的特有的模块方法，并不是语言标准，所以在 vite 中不再能使用 require context。但如果完全改为开发者手动 import 模块，一来是对已有代码改动容易产生模块导入的遗漏；二来是放弃了这种「灵活」的机制，对后续的开发模式也会有一定改变。但好在 vite2.0 提供了 glob 模式的模块导入。该功能可以实现上述目标。当然，会需要做一定的代码改动：

1
2
3
4
5
6

const routesModules = import.meta.globEager%&-l-t%{default: unknown[]}%&-g-t%('./modules/**/routes.ts');
const routes = Object
  .keys(routesModules)
  .reduce%&-l-t%any[]%&-g-t%((pre, k) =%&-g-t% [...pre, ...routesMod[k].default], []);

export default new VueRouter({ routes });

主要就是将 require.context 改为 import.meta.globEager，同时适配返回值类型。当然，为了支持 types，可以为 ImportMeta 接口添加一些类型：

1
2
3
4
5
6

declare global {
  interface ImportMeta {
    env: Record%&-l-t%string, unknown%&-g-t%;
+   globEager%&-l-t%T = unknown%&-g-t%(globPath: string): Record%&-l-t%string, T%&-g-t%;
  }
}

此外再提一下，import.meta.globEager 会在构建时做静态分析将代码替换为静态 import 语句。如果希望能支持 dynamic import，请使用 import.meta.glob 方法。

9、API 代理

vite2.0 本地开发时（DEV 模式）仍然提供了一个 HTTP server，同时也支持通过 proxy 项设置代理。其背后和 webpack 一样也是使用了 http-proxy，因此针对 vue-cli 的 proxy 设置可以迁移到 vite 中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';
import { createVuePlugin } from 'vite-plugin-vue2';
+ import proxy from './src/tangram/proxy-table';

export default defineConfig({
  plugins: [
    tsconfigPaths(),
    createVuePlugin(),
  ],
+ server: {
+   proxy,
+ }
});

10、HTML 内容插入

在基于 vue-cli 中我们可以利用 webpack 的 HtmlWebpackPlugin 来实现 HTML 中值的替换，例如 %&-l-t%%= htmlWebpackPlugin.options.title %%&-g-t% 这种形式来将该处模板变量在编译时，替换为实际的 title 值。要实现这样的功能也非常简单，例如 vite-plugin-html 。这个插件基于 ejs 来实现模板变量注入，通过 transformIndexHtml 钩子，接收原始 HTML 字符串，然后通过 ejs 渲染注入的变量后返回。

下面是迁移后，使用 vite-plugin-html 的配置方式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';
import { createVuePlugin } from 'vite-plugin-vue2';
+ import { injectHtml } from 'vite-plugin-html';

export default defineConfig({
  plugins: [
    tsconfigPaths(),
    createVuePlugin(),
+   injectHtml({
+     injectData: {
+       title: '用户管理系统',
+     },
    }),
  ],
  server: {
    proxy,
  },
});

对应的需求修改一下 HTML 的模板变量写法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

%&-l-t%!DOCTYPE html%&-g-t%
%&-l-t%html lang="en"%&-g-t%

%&-l-t%head%&-g-t%
  %&-l-t%meta charset="utf-8"%&-g-t%
  %&-l-t%meta http-equiv="X-UA-Compatible" content="IE=edge"%&-g-t%
  %&-l-t%meta name="viewport" content="width=device-width,initial-scale=1.0"%&-g-t%
- %&-l-t%title%&-g-t%%&-l-t%%= htmlWebpackPlugin.options.title %%&-g-t%%&-l-t%/title%&-g-t%
+ %&-l-t%title%&-g-t%%&-l-t%%= title %%&-g-t%%&-l-t%/title%&-g-t%
%&-l-t%/head%&-g-t%

%&-l-t%body%&-g-t%
  %&-l-t%noscript%&-g-t%
-   We're sorry but %&-l-t%%= htmlWebpackPlugin.options.title %%&-g-t% doesn't work properly without JavaScript enabled.
+   We're sorry but %&-l-t%%= title %%&-g-t% doesn't work properly without JavaScript enabled.
  %&-l-t%/noscript%&-g-t%
  %&-l-t%div id="app"%&-g-t%%&-l-t%/div%&-g-t%
  %&-l-t%script type="module" src="/src/main.ts"%&-g-t%%&-l-t%/script%&-g-t%
%&-l-t%/body%&-g-t%

%&-l-t%/html%&-g-t%

11、兼容性处理

在项目背景介绍上有提到该项目对兼容性要求很低，所以这块在迁移中实际并未涉及。

当然，如果对兼容性有要求的项目，可以使用 @vitejs/plugin-legacy 插件。该插件会打包出两套代码，一套面向新式浏览器，另一套则包含各类 polyfill 和语法兼容来面向老式浏览器。同时在 HTML 中使用 module/nomodule 技术来实现新/老浏览器中的「条件加载」。

总结

该项目包含 1897 个模块文件（包括 node_modules 中模块），迁移前后的构建（无缓存）耗时如下：

可以看到，在 DEV 模式下 vite2 构建效率的提升非常明显，这也是因为其在 DEV 模式下只做一些轻量级模块文件处理，不会做较重的打包工作，而在生产模式下，由于仍然需要使用 esbuild 和 rollup 做构建，所以在该项目中效率提升并不明显。

以上就是笔者在做 vue-cli 迁移 vite 2.0 时，遇到的一些问题。都是一些比较小的点，整体迁移上并未遇到太大的阻碍，用了不到半天时间就迁移了。当然，这也有赖于近年来 JavaScript、HTML 等标准化工作使得我们写的主流代码也能够具备一定的统一性。这也是这些前端工具让我们「面向未来」编程带来的一大优点。希望这篇文章能够给，准备尝试迁移到 vite 2.0 的各位朋友一些参考。

之前在使用一些开源项目时，经常会看到在控制台输出项目大大的 LOGO。例如：

• hexo minos 主题启动时在控制台里会显示「MINOS」文案
• fis3 启动时也会有显示「FIS」

添加这种大号「艺术字」可以达到「品牌露出」的效果，当然，也是程序员特有「情趣」的体现。 😄

但它们的实现方式无外乎把编排好的 Logo 通过 console.log 输出。这种方式问题在于它几乎没有任何复用能力，而且一些需要转义的情况还会导致字符串的可维护性极差。因此，我花了一个周末的时候，实现了一个易用的、可复用的控制台「艺术字」lib。这样，下次有新的需求，只需要把正常的文本传给它，它就可以帮你自动编排与打印。

1. 目标

正如上节所说，目前一般项目的做法都是自定写一串特定的文本，例如 minos：

1
2
3
4
5
6
7
8

logger.info(`=======================================
███╗   ███╗ ██╗ ███╗   ██╗  ██████╗  ███████╗
████╗ ████║ ██║ ████╗  ██║ ██╔═══██╗ ██╔════╝
██╔████╔██║ ██║ ██╔██╗ ██║ ██║   ██║ ███████╗
██║╚██╔╝██║ ██║ ██║╚██╗██║ ██║   ██║ ╚════██║
██║ ╚═╝ ██║ ██║ ██║ ╚████║ ╚██████╔╝ ███████║
╚═╝     ╚═╝ ╚═╝ ╚═╝  ╚═══╝  ╚═════╝  ╚══════╝
=============================================`);

还有 fis3 这种由于需要添加转义所以显得凌乱不好维护的

1
2
3
4
5
6
7
8
9
10
11
12

logo = [
      '   /\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\  /\\\\\\\\\\\\\\\\\\\\\\     /\\\\\\\\\\\\\\\\\\\\\\   ',
      '   \\/\\\\\\///////////  \\/////\\\\\\///    /\\\\\\/////////\\\\\\        ',
      '    \\/\\\\\\                 \\/\\\\\\      \\//\\\\\\      \\///  ',
      '     \\/\\\\\\\\\\\\\\\\\\\\\\         \\/\\\\\\       \\////\\\\\\              ',
      '      \\/\\\\\\///////          \\/\\\\\\          \\////\\\\\\          ',
      '       \\/\\\\\\                 \\/\\\\\\             \\////\\\\\\      ',
      '        \\/\\\\\\                 \\/\\\\\\      /\\\\\\      \\//\\\\\\  ',
      '         \\/\\\\\\              /\\\\\\\\\\\\\\\\\\\\\\ \\///\\\\\\\\\\\\\\\\\\\\\\/   ',
      '          \\///              \\///////////    \\///////////     ',
      ''
    ].join('\n');

这种些方式都是通过「硬编码」来实现的，如果有了新项目或需求变动还得重新编排调整。

因此，准备实现一种能够根据输入的字符串进行自动排版展示的控制台「艺术字」打印库，例如通过 yo('yoo-hoo') 就会输出：

1
2
3
4
5
6
7
8

/\\\    /\\\  /\\\\\\\\      /\\\\\\\\                /\\\    /\\\    /\\\\\\\\      /\\\\\\\\
\/\\\   /\\\ /\\\_____/\\\  /\\\_____/\\\             \/\\\   \/\\\  /\\\_____/\\\  /\\\_____/\\\
  \/_\\\/\\\ \/\\\    \/\\\ \/\\\    \/\\\             \/\\\   \/\\\ \/\\\    \/\\\ \/\\\    \/\\\
     \/_\\\\  \/\\\    \/\\\ \/\\\    \/\\\  /\\\\\\\\\ \/\\\\\\\\\\\ \/\\\    \/\\\ \/\\\    \/\\\
        \/\\\  \/\\\    \/\\\ \/\\\    \/\\\ \/_______/  \/\\\____/\\\ \/\\\    \/\\\ \/\\\    \/\\\
         \/\\\  \/\\\    \/\\\ \/\\\    \/\\\             \/\\\   \/\\\ \/\\\    \/\\\ \/\\\    \/\\\
          \/\\\  \/_/\\\\\\\\\  \/_/\\\\\\\\\              \/\\\   \/\\\ \/_/\\\\\\\\\  \/_/\\\\\\\\\
           \/_/     \/_______/     \/_______/               \/_/    \/_/    \/_______/     \/_______/

下次如果文案改了，直接换下字符串参数就行 —— yo('new-one')：

1
2
3
4
5
6
7
8

/\\\\\     /\\\  /\\\\\\\\\\  /\\\  \\\  \\\                /\\\\\\\\    /\\\\\     /\\\  /\\\\\\\\\\
\/\\\ \\\  \/\\\ \/\\\_____/  \/\\\  \\\  \\\              /\\\_____/\\\ \/\\\ \\\  \/\\\ \/\\\_____/
 \/\\\ /\\\ \/\\\ \/\\\        \/\\\  \\\  \\\             \/\\\    \/\\\ \/\\\ /\\\ \/\\\ \/\\\
  \/\\\  /\\\ /\\\ \/\\\\\\\\\\ \/\\\  \\\  \\\  /\\\\\\\\\ \/\\\    \/\\\ \/\\\  /\\\ /\\\ \/\\\\\\\\\\
   \/\\\ \/\\\ /\\\ \/\\\_____/  \/\\\  \\\  \\\ \/_______/  \/\\\    \/\\\ \/\\\ \/\\\ /\\\ \/\\\_____/
    \/\\\ \ /\\\ \\\ \/\\\        \/\\\ \\\\\ \\\             \/\\\    \/\\\ \/\\\ \ /\\\ \\\ \/\\\
     \/\\\  \/_\\\\\\ \/\\\\\\\\\\ \/\\\\\__/\\\\\             \/_/\\\\\\\\\  \/\\\  \/_\\\\\\ \/\\\\\\\\\\
      \/_/    \/____/  \/________/  \/_/      \/_/                \/_______/   \/_/    \/____/  \/________/

总结来说，就是实现一个通用的、可复用的控制台「艺术字」打印功能。基于这个目标开发了 yoo-hoo 这个库。

下面来说说大致怎么实现。

2. 如何实现

和其他字体显示的需求类似，我们可以将功能抽象为三个部分：

1. 字体库的生成
2. 字体的排版
3. 字体的渲染

这里我们先说一下字体的渲染。

2.1. 字体渲染

之所以先说这部分，是因为它会影响排版信息的输出格式。

其实字体渲染这部分并没有什么特别的，我们在控制台这个环境，受限于 API，基本就是使用 console.log 来将内容「渲染」到屏幕上。不过，正是这里的「渲染」形式的限制，会倒推我们的排版方式。

我们知道，控制台基本都是单行顺序渲染的，大致就是「Z」字型。同时，由于我们的「艺术字」会占据多行，所以最终的渲染不是按单个字顺序渲染的，需要先排好版，然后按行来逐步渲染到屏幕上。

这有点像是咱们常见的打印机。如果你要打印一个苹果，它会从上往下逐步打印出这个苹果，而不是直接像盖章那样直接印刷一个苹果。

下面我们会先介绍字体库的生成，而不是紧接挨着的字体排版。因为排版是一个承上启下的过程，当我们确定了上下游环节，这块的逻辑自然也就确定了。

2.2. 字体库生成

当我们想要实现可复用能力时，因此我们需要找到或者抽象出系统内逻辑上的最小可复用单元 —— 在这里显然就是字符。简单来说，对于输入字符串 JS 时，如果我们能找到对应的 J 和 S 的字符表示形式，辅以排版，理论上就有能力实现我们的目标。这有点像是咱们老祖宗的活字印刷术。

所以在字体库这里，我们会有一个字义与字型的映射。这个其实和咱们前端常见的字体文件内格式的思想一样，都需要有这么一个映射关系。

字型哪里来呢？好吧，我也是用了一个笨办法 —— 自己「手绘」😂。举个例子，下面就是我「手绘」的 1：

1
2
3
4
5
6
7
8
9

1
  /\\\
/\\\\\\
\/__/\\\
    \/\\\
     \/\\\
      \/\\\
      /\\\\\\\
      \/_____/

绘制的过程是枯燥的，好再很多字型的局部是有一定复用的，简化了这项繁琐的工作。当然，这只是一次性的工作，一旦创建好一类「字体」，以后就不需要再重复这项工作了。

我把上面这个内容存在一个单独的文件中，目前直接以 .txt 为后缀，这就是我们的字体原始格式。之所以不放在 .js 中，是因为 JavaScript 中 \ 是想要转义的，这样文本的视觉和最后的呈现效果就不一致了，不利于调试和维护。

原始字体文件分为两部分：

• 上面第一行是字义，支持一个多个字义对应一个图形。例如 · 和 * 我使用了同一个图形。多个字义间空格分割，不换行。
• 除去第一行，剩下的内容就是字型。

理论上，我们可以以这个原始字体文件来作为字体库了，通过 NodeJS 中的 fs 模块读取并解析文件内容即可得到映射关系。

但我希望它也能在非 NodeJS 环境（例如浏览器）中使用，所以不能依赖 fs 模块。这里做了一个原始文件的解析脚本，生成对应的 JS 模块。由于我们并不直接维护这些生成的 JS 模块，所以它的可读性不重要，可以设计数据格式的时候可以完全面向后续的排版流程。

首先实现一个简单的解析器来解析第一行的字义。这也类似一个词法解析器，但由于语法规则极其弱智（简单），所以也就不用多说了，大致如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

const parseDefinition = function (line: string) {
    let token = '';
    const defs: string[] = [];
    for (const char of line) {
        if (char === ' ' && token) {
            defs.push(token);
            token = '';
        }
        if (char !== ' ') {
            token += char;
        }
    }
    if (token) {
        defs.push(token);
    }
    return defs;
}

下面就是处理字型部分。之所以需要处理字型，是因为上面提到的转义问题。由于我们在原始格式中使用了 \ 来进行字型展示，而将其直接放入生成的 JS 文件中这个 \ 就变为了转义符，要想正常展示需要变为 \\。一种方式是正则匹配，将所有源文本中的 \ 替换为 \\ 再写入。但我选择了另一种方式。

将字符通过 .charCodeAt 方法转为 char code 存储，读取字体信息时再通过 String.fromCharCode 转回来。原来的字符串变成了数字类型的数组，这样就没有特殊字符的问题了。最后，通过拼接文本并生成 JS 文件来将原始的、利于人维护的字体文件，转成了编译 JS 工作的模块。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

const arrayToString = %&-l-t%T%&-g-t%(arr: T[]) =%&-g-t% '[' + arr.map(d =%&-g-t% `'${d}'`).join(',') + ']';

const text = parsedFonts.reduce((t, f, idx) =%&-g-t% {
    return t + (
        '\n/**\n'
        + f.content
        + '\n*/\n'
        + `fonts[${idx}] = {\n`
        + `  defs: ${arrayToString(f.defs)},\n`
        + `  codes: ${arrayToString(f.codes)}\n`
        + '};\n'
    );
}, '');
const moduleText = (
    'const fonts = [];\n'
    + text
    + 'module.exports.fonts = fonts;\n'
);

fs.writeFileSync(fontFilepath, moduleText, 'utf-8');

其中 defs 就是这个字型对应的字义列表，codes 则是字型的 char code 数组，所有的字体都被放在一个 JS 文件中。

这里提一下，第 3 行的 parsedFonts 就是遍历所有原始字体文件解析到的内容，因此得到这部分也是需要通过 NodeJS 的 fs 模块来递归读取源文件目录下的字体文件的。算是基操，就不用展开了。

由于这部分是可以提前解析编译的，一旦生成了 JS 模块后就不会对 NodeJS 运行时有依赖，所以保证了其依然可以运行在浏览器中。

2.3. 字体的排版

我们的字体格式确定了，目标的渲染方式也确定了。最后就可以填充这部分的逻辑实现了。

具体排版上会遇到一些细节点，例如不等高字体的空行填充、最大行宽的换行判断（需要用户执行行宽），不过这些都是小点，处理也不太复杂。这里可能介绍一下稍有特殊的一块 —— 字间距调整。

我们知道，一些艺术字的倾斜程度可能很大，例如这个字符「1」：

1
2
3
4
5
6
7
8

  /\\\
/\\\\\\
\/__/\\\
    \/\\\
     \/\\\
      \/\\\
      /\\\\\\\
      \/_____/

如果按简单的矩形型包围盒来分配空间，大概会是下面这样：

前后两个字体，即使设置为最小间距（0），仍然会距离很远，这样就破坏了一定的显示效果。例如上图中我两个包围盒间距其实只有 1，但看起来就很大。我们实际希望的可能是下面这样：

间距为 1 时，两个字符「1」调整为在最近的地方间距为 1。如果要更宽的效果可以设置更多间距。这个处理起来主要就是需要算出最大的「挤压空间」（即两个盒子最大支持的交叉空间）。最开始渲染的时候说了，我们是按 console 出的行来存储的与打印的，举个例子，这个「1」高度为 8 ，所以渲染的时候就是一个 8 个元素的字符串数组：

1
2
3
4
5
6
7
8
9
10

const lines = [
    '  /\\\',
    '/\\\\\\',
    '\/__/\\\',
    '    \/\\\',
    '     \/\\\',
    '      \/\\\',
    '      /\\\\\\\',
    '      \/_____/',
];

渲染的时候直接 lines.forEach(l =%&-g-t% console.log(l)) 即可。

💣 注意，为了便于读者阅读，上面的 lines 数组内的字符串我没有加上转义，它是不合法的！只是为了展示起来更便于阅读理解，实际中不能这么写。

最大缩进（缩进这个词不准确，但希望大家能够理解那个意思）的计算只需要知道之前的每个 line 尾部对应有多少空格，同时需要再其后新添加字符每个 line 前面又分别有多少空格，综合两者，再遍历所有的 line 取一个最小值即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// calc the prefix space
const prefixSpace = function (str: string) {
    const matched = /^\s+/gu.exec(str);

    return matched ? matched[0].length : 0;
};

// calc the tail space
const tailSpace = function (str: string) {
    const matched = /\s+$/gu.exec(str);

    return matched ? matched[0].length : 0;
};

// calc how many spaces need for indent for layout
// overwise the gap between two characters will be different
const calcIndent = function (lines: string[], charLines: string[]): number {
    // maximum indent that won't break the layout
    let maxPossible = Infinity;

    for (let i = 1; i %&-l-t% lines.length; i++) {
        const formerTailNum = tailSpace(lines[i]);
        const latterPrefixNum = prefixSpace(charLines[i]);

        maxPossible = Math.min(maxPossible, formerTailNum + latterPrefixNum);
    }

    return maxPossible;
};

最后 calcIndent 方法返回的就是新字符需要向前缩进（或者说缩紧）的值。最后渲染的时候根据这个值来调整每行连接时添加的空格数即可。

捎带一提，之前的字体格式 load 进来会被转换为类似字典的格式 —— 字义作为 key，字型等一系列属性作为 value：

1
2
3
4
5
6
7
8
9
10
11

const dictionary = {
    'a': {
        lines: [...],
        width: ...,
        height: ...,
    },
    'b': {
        ...
    },
    ...
}

这样遍于 split 完用户传入的字符串后，更简单的索引到对应的字型和字体信息。

2.4. 其他

当然，其他还会有一些工作，包括

• 支持颜色
• 支持返回排版完的 lines 让用户自己渲染
• 支持用户自定义调整字间距

这些目前实现上遇到的问题不大，篇幅原因也就不说了。具体的代码可以在 Github 上看到。

3. 总结

实现可复用的控制台“艺术字”功能，总的来说并没有太多复杂的点，整体的流程模型就是

生成字体库 --%&-g-t% 字体排版 --%&-g-t% 渲染文本

这对于前端来说应该是非常好理解的。

做这个项目也确实是自己在工作中希望给一些库加上这种 logo 或者 banner 展示，但每次重复枯燥的工作确实令人反感。所以想了下可行性之后就搞了 yoo-hoo 这么个小玩意儿，如果大家也遇到类似的问题，希望能有所帮助。

1

npm i yoo-hoo

4. 最后

目前 yoo-hoo@1.0.x 内置了一套 26 个字母（A-Z）、10 个数字（0-9）、· * - | 这些字符的字体库。

考虑到单一的字型和有限的字体量肯定不能满足所有需求，所以开发时代码结构就留下了支持外部扩展的模式。

后续可以把 2.2 节中的字体源文件解析工具独立出来，支持用户「手绘」自己的字型，用工具生成对应格式后，将字体的 JS 模块传入 yo 方法中作为扩展字体加载。

字体源文件的「手绘」虽有成本，但所见即所得，编写难度不大 🐶 同时也算是一劳永逸。

近期，随着 vue3 的各种曝光，vite 的热度上升，与 vite 类似的 snowpack 的关注度也逐渐增加了。目前（2020.06.18）snowpack 在 Github 上已经有了将近 1w stars。

snowpack 的代码很轻量，本文会从实现原理的角度介绍 snowpack 的特点。同时，带大家一起看看，作为一个以原生 JavaScript 模块化为核心的年轻的构建工具，它是如何实现“老牌”构建工具所提供的那些特性的。

1. 初识 snowpack

近期，随着 vue3 的各种曝光，vite 的热度上升，与 vite 类似的 snowpack 的关注度也逐渐增加了。目前（2020.06.18）snowpack 在 Github 上已经有了将近 1w stars。