1. 从“context-mode”这个命名说起：它到底在解决什么问题

第一次看到context-mode这个词，很多人会下意识地把它当成某个库里的枚举值或者配置项。但如果你在代码里真的去搜，会发现它并不是某个主流框架的标准 API。它更像是一个被开发者口口相传、逐渐固化成概念的说法，用来描述一类非常具体的问题：同一段逻辑，在不同上下文环境下需要表现出不同的行为模式，而你又不想为此维护多套代码分支。

举个最直白的例子。你写了一个数据处理的函数，在命令行里跑的时候，你希望它把结果直接打印到终端；在 Web 服务里被调用的时候，你希望它返回 JSON；在单元测试里跑的时候，你希望它返回一个可以被断言的纯数据结构。这三个场景下，核心计算逻辑完全一样，变的只是“输出到哪儿”和“以什么形式输出”。如果你用if (isCLI) ... else if (isWeb) ... else if (isTest) ...来写，代码很快就会变成一团乱麻。而context-mode这个思路，就是把这层判断从业务逻辑里抽出来，让上下文自己决定当前处于什么模式，业务代码只负责“做事”，不负责“判断自己在哪儿做事”。

这个思路的价值在于，它把环境感知和业务执行这两件事彻底解耦了。环境感知是基础设施层面的事，业务执行是领域逻辑层面的事，两者混在一起，就是典型的架构腐化起点。我见过太多项目，一开始只是加一个if (debug)，后来变成if (debug && !production && platform !== 'web')，最后没人敢动那段代码，因为谁也不知道删掉一个条件会影响到哪个角落。

所以，当你看到context-mode这个标题时，不要把它理解成某个具体的工具或库。它代表的是一种设计取向：让上下文成为一等公民，让模式切换变成显式声明而非隐式判断。接下来我会从实际落地的角度，把这个思路拆开讲清楚，包括它适合什么场景、不适合什么场景、怎么设计一套可维护的上下文模式体系，以及我在真实项目里踩过的那些坑。

2. 上下文模式的核心机制：不是 if-else 的包装，而是关注点分离

2.1 上下文到底包含哪些维度

很多人一提到“上下文”，脑子里只有“运行环境”这一个维度。实际上，在一个稍微正经点的系统里，上下文至少包含以下几层信息：

context-mode要做的，就是把这些维度统一抽象成一个上下文对象，然后在关键决策点根据这个对象的当前状态来选择行为模式。注意，这里说的是“选择行为模式”，而不是“执行具体逻辑”。行为模式是策略层面的东西，具体逻辑是执行层面的东西，两者必须分开。

我见过一个反例：有人在业务函数里直接读环境变量，然后根据NODE_ENV的值决定要不要发告警邮件。结果测试环境跑集成测试的时候，因为NODE_ENV没设对，给全组人发了一百多封告警邮件。这就是典型的上下文判断散落在业务代码里导致的灾难。正确的做法是，上下文对象在应用启动时就被确定下来，业务代码只问“当前模式是什么”，而不问“当前环境变量是什么”。

2.2 模式切换的三种实现路径

实现context-mode的思路大致有三种，各有各的适用场景，我逐一分析。

第一种：策略注册表。你定义一个模式到处理器的映射表，比如{ cli: CliHandler, web: WebHandler, test: TestHandler }，然后在入口处根据上下文选择对应的处理器。这种方式的优点是扩展性好，新增一个模式只需要注册一个新的处理器，不需要改任何现有代码。缺点是如果模式之间共享大量逻辑，你需要在处理器之间做组合或者继承，容易产生层次过深的问题。

第二种：中间件管道。把上下文相关的处理逻辑做成一系列中间件，每个中间件负责一个维度的判断和转换。比如第一个中间件处理输入解析，第二个中间件处理权限校验，第三个中间件处理输出格式化。这种方式的优点是逻辑清晰，每个中间件只关心一件事。缺点是调试起来比较麻烦，因为一个请求经过多个中间件之后，你很难一眼看出最终的行为是由哪个中间件决定的。

第三种：上下文注入。在函数调用链的起点创建一个上下文对象，然后通过参数传递或者依赖注入的方式，把这个对象传到每一个需要它的地方。业务函数根据上下文对象里的模式字段来决定行为。这种方式的优点是显式、可追踪，你打开任何一个函数，都能从签名里看出它依赖什么上下文。缺点是需要传递的对象可能很大，而且如果调用链很深，参数传递会很繁琐。

我在实际项目里最常用的是第一种和第三种的混合：在应用入口用策略注册表确定顶层模式，然后把上下文对象注入到业务层，业务层内部再用小的策略表来处理局部模式切换。这样既保证了顶层结构的清晰，又避免了深层调用链的参数传递问题。

2.3 为什么不能直接用依赖注入框架替代

有人可能会问：我用依赖注入框架，把不同环境下的实现类注入进去，不就行了吗？为什么还要单独搞一套context-mode？

这个问题问得好。依赖注入解决的是实现替换的问题，而context-mode解决的是行为选择的问题。这两者有重叠，但不完全一样。

举个例子。你的系统需要发送通知。在开发环境下，你希望通知只打印到控制台；在测试环境下，你希望通知写入一个内存队列供断言；在生产环境下，你希望通知真正发出去。用依赖注入，你可以定义Notifier接口，然后提供ConsoleNotifier、MemoryNotifier、RealNotifier三个实现，在启动时根据环境注入不同的实现。这没问题。

但是，如果同一个进程里需要同时支持多种模式呢？比如一个服务既接受 HTTP 请求，又消费消息队列，还提供 CLI 管理命令。HTTP 请求的通知要发到用户邮箱，消息队列的通知要写入审计日志，CLI 命令的通知要打印到终端。这时候依赖注入就不够用了，因为注入是在启动时确定的，而模式是在运行时根据调用来源动态变化的。context-mode的核心价值就在这里：它支持运行时动态模式切换，而依赖注入通常只支持启动时静态实现替换。

当然，两者可以结合使用。顶层用依赖注入确定基础设施，运行时用context-mode处理动态行为选择。这是我在复杂系统里最推荐的组合方式。

3. 落地一套 context-mode 体系：从目录结构到代码组织

3.1 目录结构设计

一套可维护的context-mode体系，目录结构应该让“模式”这个概念在文件系统层面就可见。我通常采用这样的组织方式：

src/ contexts/ index.ts # 上下文对象的定义和创建逻辑 detector.ts # 从运行环境中检测当前上下文的逻辑 modes/ cli.ts # CLI 模式下的行为定义 web.ts # Web 模式下的行为定义 test.ts # 测试模式下的行为定义 core/ services/ # 业务逻辑，不直接依赖具体模式 handlers/ # 模式相关的处理器，按模式分目录 entry/ cli.ts # CLI 入口，创建 CLI 上下文 server.ts # HTTP 入口，创建 Web 上下文

这个结构的关键在于contexts/modes/目录。每个模式一个文件，文件里定义该模式下所有需要变化的行为。当你要新增一个模式时，只需要在这个目录下加一个文件，然后在detector.ts里注册检测逻辑。业务代码完全不用动。

我见过很多项目把模式相关的代码散落在各个业务模块里，比如userService.cli.ts、userService.web.ts这种命名方式。这种方式在模式数量少的时候还能忍，一旦模式超过三个，文件数量就会爆炸，而且你很难一眼看出某个模式到底影响了哪些业务模块。集中式的modes/目录解决了这个问题。

3.2 上下文对象的字段设计

上下文对象不要设计得太胖。我见过有人把整个process.env塞进上下文对象，结果这个对象序列化之后有几十 KB，日志里打出来根本没法看。上下文对象应该只包含影响行为决策的最小信息集。

我的经验是，上下文对象包含以下几类字段就够了：

• mode: 当前主模式，比如'cli' | 'web' | 'test'，这是最重要的字段。
• flags: 一组布尔标志，比如isDebug、isDryRun、isVerbose，用来控制细节行为。
• metadata: 一些元信息，比如requestId、userId、startTime，用于日志和追踪。
• capabilities: 当前上下文具备的能力，比如canWriteFile、canSendNetwork、canPromptUser，业务代码根据这些能力来决定是否执行某些操作。

capabilities这个设计是我踩坑之后加上的。早期我直接用mode来判断，业务代码里到处是if (ctx.mode === 'cli')。后来发现，有些能力在多个模式下是共享的，比如 CLI 和 Web 都能写文件，但测试模式不能。如果只用mode判断，就会写出if (ctx.mode === 'cli' || ctx.mode === 'web')这种重复逻辑。改成if (ctx.capabilities.canWriteFile)之后，逻辑清晰多了，而且新增模式时只需要声明它具备哪些能力，不需要改业务代码。

3.3 模式检测的时机与策略

模式检测应该在应用启动的最早阶段完成，而且只做一次。不要在每次函数调用时都去检测当前模式，那样性能开销不说，逻辑上也会变得混乱——万一检测逻辑本身依赖某个还没初始化的东西呢？

检测策略通常是按优先级依次尝试：

1. 如果存在显式的命令行参数（比如--mode=cli），直接用这个。
2. 否则检查环境变量（比如APP_MODE）。
3. 否则根据运行时的特征推断，比如process.stdin.isTTY为真说明是交互式终端，process.env.NODE_ENV === 'test'说明是测试环境。
4. 如果都检测不到，使用一个安全的默认模式，通常是'cli'或者'unknown'。

这里有个坑要注意：不要根据NODE_ENV来推断模式。NODE_ENV是给构建工具和第三方库看的，它只有development、production、test三个约定值，不足以表达你的业务模式。我见过有人用NODE_ENV=production来判断是否应该发送真实通知，结果在预发环境（也是production）里把测试通知发给了真实用户。正确的做法是定义一个独立的APP_MODE变量，和NODE_ENV解耦。

3.4 业务代码如何消费上下文

业务代码消费上下文的方式，决定了这套体系最终是清晰还是混乱。我的原则是：业务函数只读上下文，不写上下文；只根据上下文做分支，不根据上下文做副作用。

什么意思？举个例子。一个发送通知的函数，它应该这样写：

function sendNotification(ctx: Context, userId: string, message: string) { if (!ctx.capabilities.canSendNetwork) { ctx.logger.info(`[dry-run] would send to ${userId}: ${message}`); return; } // 真正发送通知的逻辑 return notificationService.send(userId, message); }

注意，这个函数没有去判断ctx.mode === 'test'，而是判断ctx.capabilities.canSendNetwork。这样，无论未来新增什么模式，只要该模式声明了canSendNetwork: false，这个函数就会自动进入 dry-run 分支，不需要改一行代码。

另一个原则是：上下文对象应该是不可变的。一旦创建，就不应该在运行过程中被修改。如果某个中间件需要改变行为，它应该创建一个新的上下文对象，而不是修改原有的。这样可以避免“上下文在调用链中被意外篡改”这类难以排查的问题。我在一个项目里遇到过，某个中间件为了临时关闭日志，直接把ctx.flags.isVerbose = false，结果这个修改影响了后续所有请求，因为上下文对象是单例的。改成不可变之后，每个请求都有自己的上下文副本，问题就消失了。

4. 真实场景拆解：三种典型模式下的行为差异

4.1 CLI 模式：交互性与退出码

CLI 模式最特殊的地方在于，它和用户的交互是同步的、有状态的。用户输入一个命令，程序执行，输出结果，然后退出。这个过程中，程序需要处理用户的输入提示、进度显示、错误信息格式化，以及最重要的——退出码。

在context-mode体系里，CLI 模式通常声明以下能力：canPromptUser: true、canWriteFile: true、canSendNetwork: true、isInteractive: true。业务代码根据isInteractive来决定是否显示进度条，根据canPromptUser来决定是否弹出确认对话框。

退出码是 CLI 模式独有的关注点。在 Web 模式里，错误通过 HTTP 状态码表达；在 CLI 模式里，错误通过退出码表达。我通常会在上下文对象里加一个exitCode字段，业务代码在遇到错误时设置这个字段，然后在入口处统一根据它来调用process.exit()。这样业务代码不需要直接调用process.exit()，测试的时候也更容易断言。

// entry/cli.ts const ctx = createContext({ mode: 'cli' }); try { await runCommand(ctx, process.argv.slice(2)); } catch (err) { ctx.logger.error(err.message); ctx.exitCode = 1; } process.exit(ctx.exitCode);

这里有个细节：process.exit()会立即终止进程，不会等待未完成的异步操作。如果你的程序里有正在写入的文件流或者正在发送的网络请求，直接退出会导致数据丢失。正确的做法是设置process.exitCode而不是调用process.exit()，让 Node.js 在事件循环清空后自然退出。只有在确实需要强制退出时才调用process.exit()。

4.2 Web 模式：请求隔离与并发安全

Web 模式和 CLI 模式最大的区别在于并发。CLI 模式一次只处理一个命令，上下文是全局唯一的；Web 模式同时处理多个请求，每个请求都有自己的上下文。这意味着上下文对象不能是单例，必须每个请求创建一个。

在context-mode体系里，Web 模式的上下文通常在中间件里创建，然后挂载到请求对象上。后续的处理器从请求对象里取上下文，而不是从全局变量里取。这是保证并发安全的关键。

// middleware/context.ts export function contextMiddleware(req, res, next) { req.ctx = createContext({ mode: 'web', metadata: { requestId: generateRequestId(), userId: req.user?.id, startTime: Date.now(), }, capabilities: { canPromptUser: false, canWriteFile: false, canSendNetwork: true, isInteractive: false, }, }); next(); }

注意canPromptUser: false和isInteractive: false。Web 请求不能弹出交互式对话框，也不能假设有终端可以显示进度条。如果业务代码里有一个函数在 CLI 模式下会提示用户确认，在 Web 模式下它应该直接抛出错误或者返回一个需要确认的响应，而不是阻塞等待。这就是capabilities字段的价值：它让业务代码能够以统一的方式处理不同模式下的能力差异。

另一个 Web 模式特有的问题是超时。CLI 命令可以跑几分钟甚至几小时，但 HTTP 请求通常有超时限制。上下文对象里应该包含一个deadline字段，业务代码在执行耗时操作前检查这个字段，如果剩余时间不足就提前终止。这比在网关层硬性切断连接要优雅得多，因为业务代码有机会做清理工作。

4.3 测试模式：确定性与可断言性

测试模式的核心诉求是确定性。同样的输入必须产生同样的输出，不能依赖当前时间、随机数、网络状态或者文件系统。context-mode在测试模式下的作用，就是把这些不确定性来源全部替换成可控的桩。

测试模式的上下文通常声明canSendNetwork: false、canWriteFile: false、canPromptUser: false，并且提供一个clock字段用于获取当前时间，一个random字段用于生成随机数。业务代码不直接调用Date.now()或Math.random()，而是通过上下文对象获取。这样在测试时，你可以注入一个固定时间的时钟和一个固定序列的随机数生成器，让测试结果完全可预测。

// core/services/order.ts function createOrder(ctx: Context, items: Item[]) { const orderId = ctx.random.uuid(); const createdAt = ctx.clock.now(); // ... }

这个模式一开始会让人觉得繁琐，但一旦习惯之后，你会发现测试变得极其稳定。我再也没有遇到过“这个测试昨天还能过今天怎么就挂了”的情况，因为所有不确定性来源都被上下文接管了。

测试模式还有一个容易被忽略的点：清理逻辑。测试结束后，上下文应该负责清理它创建的所有资源，比如临时文件、内存队列、数据库连接。我通常会在上下文对象上挂一个cleanup函数数组，业务代码在创建资源时把清理函数注册进去，测试框架在afterEach里统一调用。这样就不会出现测试之间互相污染的问题。

5. 踩坑实录：那些让我重构三次的上下文陷阱

5.1 上下文泄漏：当全局状态伪装成上下文

我做过一个项目，一开始为了图方便，把上下文对象挂在了全局变量上。CLI 模式下没问题，因为一次只跑一个命令。后来加了 Web 模式，问题就来了：两个并发请求，请求 A 把上下文设成mode: 'web'，请求 B 也设成mode: 'web'，看起来没问题。但请求 A 在处理过程中临时把ctx.flags.isDryRun = true，结果请求 B 读到了这个标志，行为变得莫名其妙。

这个问题的根源在于，我把“上下文”当成了“全局配置”。上下文应该是请求级别的，每个请求一份，互不干扰。全局配置是另一回事，它应该是只读的，在启动时确定，运行时不修改。两者混在一起，就是灾难。

修复方案很简单：上下文对象通过参数传递或者请求对象挂载，绝对不放在全局变量里。全局配置单独放在一个config对象里，标记为readonly，任何试图修改它的代码都会在编译时报错。

5.2 模式判断散落：从一处判断到处处判断

第二个坑是模式判断的扩散。一开始，我只在入口处判断一次模式，然后根据模式选择不同的处理器。后来需求变了：某个业务函数在 CLI 模式下需要多打印一些调试信息，在 Web 模式下不需要。于是我在那个函数里加了一个if (ctx.mode === 'cli')。再后来，另一个函数也需要类似判断，我又加了一个。半年后，代码里到处都是ctx.mode === 'cli'，新增一个模式时，我不得不全局搜索替换。

这个问题的根源在于，我把“模式”当成了行为判断的唯一依据。正确的做法是，把模式转换成能力，业务代码判断能力而不是判断模式。比如“是否需要多打印调试信息”这件事，应该抽象成ctx.capabilities.isVerbose，CLI 模式下这个能力为true，Web 模式下为false。这样业务代码里只有if (ctx.capabilities.isVerbose)，新增模式时只需要声明该模式是否具备这个能力，不需要改业务代码。

这个重构花了我整整两天时间，但之后新增模式的时间从半天缩短到了十分钟。这笔账怎么算都划算。

5.3 异步上下文丢失：await 之后的上下文去哪了

第三个坑最隐蔽。在 Node.js 里，如果你用AsyncLocalStorage来存储上下文，大部分情况下没问题。但如果你在某个地方用了setTimeout、setImmediate或者事件监听器，上下文可能会丢失。因为AsyncLocalStorage是基于异步调用链的，一旦调用链断裂，上下文就取不到了。

我遇到的具体场景是：一个 Web 请求在处理过程中，把一个任务丢到了setTimeout里异步执行。等setTimeout的回调触发时，AsyncLocalStorage.getStore()返回undefined，因为此时已经不在原来的异步调用链里了。结果那个任务里的所有日志都丢失了requestId，排查问题时完全串不起来。

解决方案是，在把任务丢到setTimeout之前，先手动捕获当前上下文，然后在回调里恢复：

const ctx = getContext(); setTimeout(() => { runWithContext(ctx, () => { // 这里的代码可以正常获取上下文 }); }, 1000);

这个坑让我意识到，上下文传递不是自动的，尤其是在跨越异步边界的时候。每次把任务交给外部调度器（定时器、事件发射器、消息队列），都要显式地传递上下文。后来我干脆封装了一个scheduleWithContext工具函数，所有异步调度都走这个函数，避免遗漏。

5.4 上下文对象的序列化陷阱

第四个坑和日志有关。我习惯把上下文对象直接打进日志，方便排查问题。但上下文对象里可能包含循环引用（比如ctx.parent = ctx），或者包含不可序列化的东西（比如函数、流对象）。直接JSON.stringify(ctx)会抛错或者产生巨大的日志。

解决方案是，给上下文对象实现一个toJSON()方法，只返回需要记录的字段。或者更简单一点，在日志中间件里手动挑选字段：

logger.info({ mode: ctx.mode, requestId: ctx.metadata.requestId, userId: ctx.metadata.userId, flags: ctx.flags, }, 'request started');

不要偷懒把整个上下文对象丢进日志。日志是给人看的，不是给机器解析的，精简比完整更重要。

6. 进阶：让 context-mode 体系具备自我演进能力

6.1 模式的能力声明与校验

当模式数量增加到五六个的时候，手动维护每个模式的能力声明就容易出错。比如你新增了一个模式，忘了声明canWriteFile，业务代码读取这个字段时得到undefined，在布尔判断里等同于false，行为可能不符合预期。

我的做法是，定义一个能力清单，每个模式必须显式声明所有能力，缺一个就在启动时报错：

const REQUIRED_CAPABILITIES = [ 'canPromptUser', 'canWriteFile', 'canSendNetwork', 'isInteractive', 'isVerbose', ] as const; function validateCapabilities(mode: string, caps: Record<string, boolean>) { for (const cap of REQUIRED_CAPABILITIES) { if (typeof caps[cap] !== 'boolean') { throw new Error(`Mode "${mode}" is missing capability "${cap}"`); } } }

这个校验在应用启动时执行，任何模式声明不完整都会立即暴露，而不是等到运行时才出现诡异行为。这个做法是我从一个同事那里学来的，他管这叫“让错误尽早发生”。我觉得这是上下文模式体系里最重要的一条工程原则。

6.2 模式之间的继承与组合

有些模式之间共享大量行为。比如'web'和'webhook'都是 Web 相关的，都具备canSendNetwork: true和isInteractive: false，区别只在于webhook不需要用户认证。如果每个模式都从头声明所有能力，会有大量重复。

我的做法是，允许模式之间继承：

const webCapabilities = { canPromptUser: false, canWriteFile: false, canSendNetwork: true, isInteractive: false, isVerbose: false, }; const modes = { web: webCapabilities, webhook: { ...webCapabilities, requiresAuth: false }, cli: { ...webCapabilities, canPromptUser: true, canWriteFile: true, isInteractive: true }, };

这样，公共能力定义一次，差异部分显式覆盖。新增模式时，先找一个最接近的现有模式继承，然后只声明差异。这比从头写一遍要快得多，也不容易遗漏。

6.3 上下文模式的文档化

最后一个进阶话题是文档化。上下文模式体系最大的风险是“只有写的人知道”。新人进来，看到ctx.capabilities.canWriteFile，不知道这个能力在哪些模式下为true，也不知道为什么某个模式不能写文件。如果没有文档，他们只能去读源码，而源码可能散落在多个文件里。

我的做法是，在contexts/modes/目录下放一个README.md，用表格列出所有模式及其能力声明，并解释每个能力为true或false的原因。这个文档不需要很正式，但必须和代码同步更新。我通常在代码审查时检查：如果某个 PR 修改了模式的能力声明，但没有更新这个文档，就打回去。

这张表放在文档最前面，任何人想了解某个模式的行为，看一眼就够了。这比读代码快十倍。

7. 我个人的经验总结：什么时候该用，什么时候不该用

context-mode这套思路不是银弹。我在一些项目里用了，效果很好；在另一些项目里用了，反而增加了复杂度。区别在哪里？

适合用的场景：同一个核心逻辑需要在多种环境下运行，且环境差异主要体现在输入输出和副作用上。比如一个数据处理管道，既要在 CLI 里跑，又要在 Web 服务里跑，还要在测试里跑。这种情况下，把环境差异抽象成上下文模式，收益非常明显。

不适合用的场景：环境差异很小，或者差异主要体现在配置上而不是行为上。比如一个纯计算函数，无论在什么环境下都是同样的输入输出，那就没必要引入上下文模式。直接写一个纯函数，让调用方处理环境差异就行了。

还有一个判断标准：如果你发现上下文对象里的字段超过十个，或者模式数量超过五个，就要警惕了。这通常意味着你的系统边界不够清晰，或者你在试图用上下文模式解决一个应该用架构分层解决的问题。上下文模式是战术层面的工具，不是战略层面的架构。它解决的是“同一段逻辑在不同环境下行为不同”的问题，不解决“系统太复杂需要拆分”的问题。

最后分享一个我在实际使用中总结的小技巧：给上下文对象加一个describe()方法，返回一个人类可读的字符串，比如"cli (interactive, verbose, can-write)"。在日志里、在错误信息里、在调试输出里，用这个字符串代替完整的上下文对象。这样既保留了关键信息，又不会让日志变得臃肿。这个技巧看起来很小，但在排查问题时能省下大量时间。