1. 从“context-mode”这个命名说起：它到底在指什么
第一次看到“context-mode”这个词，很多人会下意识地把它当成某个具体框架里的配置项，或者某个库的开关参数。但如果你在工程一线待过几年，就会发现这个词其实指向一个更底层、更普遍的问题：同一套逻辑，在不同上下文里应该表现出不同的行为模式。这不是某个语言独有的概念，而是所有需要处理“状态”和“环境”的系统都绕不开的设计命题。
我最早接触类似概念是在做前端组件库的时候。一个按钮组件，在表单里是提交按钮，在弹窗里是确认按钮，在工具栏里是图标按钮——外观不同、行为不同、可访问性属性也不同。当时我们的做法是给组件传一堆布尔值：isPrimary、isDanger、isGhost、isSmall……结果就是组件内部充满了条件判断，每加一种场景就要改一次源码。后来才意识到，真正的问题不在于“有多少种样式”，而在于“当前处于什么上下文”。一旦把上下文抽象出来，组件只需要知道自己在哪种 mode 下运行，剩下的交给 mode 自己定义。
这就是 context-mode 的核心思想：把“环境相关的行为差异”从主逻辑里剥离出来，用独立的模式定义去承载。它可以是前端组件的渲染模式，可以是后端服务的运行模式，可以是 CLI 工具的交互模式，也可以是 AI 应用里对话上下文的组织模式。命名里的“context”强调的是环境感知，“mode”强调的是行为切换，合在一起就是“根据上下文切换行为模式”的机制。
为什么这个思路值得单独拿出来讲？因为大多数人在写代码时，习惯用条件分支去处理环境差异。if (isMobile) { ... } else { ... }这种写法在场景少的时候没问题，但场景一多就会变成灾难。context-mode 提供的是另一种组织方式：把每种上下文对应的行为封装成独立的模式对象，主流程只负责“识别当前上下文”和“委托给对应模式”。这样做的好处是，新增一种上下文时不需要改动主流程，只需要新增一个模式定义。
从更宏观的视角看，context-mode 其实是一种策略模式与状态模式的融合变体。策略模式关注“算法可替换”，状态模式关注“状态驱动行为变化”，而 context-mode 关注的是“上下文驱动整体行为模式切换”。它比策略模式更重，因为一个 mode 往往包含多个策略；它比状态模式更灵活，因为上下文不一定来自内部状态，也可能来自外部环境。
我在实际项目里用这套思路重构过一个多端适配的 SDK。重构前，iOS、Android、Web 三端的差异逻辑散落在十几个文件里，每次改一处都要三端同步。重构后，每个端对应一个 mode 文件，公共逻辑抽到 core 层，mode 只负责处理端特有的行为。代码量减少了约四成，更重要的是，新人接手时只需要看一个 mode 文件就能理解某个端的行为，不用在十几个文件里跳来跳去。
所以，当你看到“context-mode”这个词时，不要只把它当成一个技术名词。它背后是一整套关于“如何优雅处理环境差异”的工程方法论。接下来我会从设计动机、核心结构、落地步骤、常见坑几个维度，把这套东西拆开讲清楚。
2. 为什么条件分支会失控：context-mode 要解决的真实痛点
2.1 条件分支的膨胀曲线比你想的更陡
很多人低估了条件分支的膨胀速度。假设一个模块有 3 个环境维度，每个维度有 2 种取值，理论上就有 8 种组合。如果每个组合都需要一点差异化处理，代码里就会出现 8 个分支。这还只是二维的简单情况。实际项目里，环境维度往往包括：运行平台、用户角色、网络状态、功能开关、版本号、地区配置……维度一多，组合数是指数级增长的。
我见过一个真实案例：一个支付流程的代码里，因为要处理“不同平台 + 不同支付渠道 + 不同用户等级 + 不同促销活动”的组合，最终出现了超过 200 个条件分支。这段代码后来没人敢改，因为改一处不知道会影响到哪些组合。这就是条件分支失控的典型症状：代码从“可读”变成“可运行但不可维护”。
context-mode 的思路是切断这种指数增长。它不试图在一个函数里处理所有组合，而是把“上下文识别”和“上下文处理”分开。识别层负责判断当前属于哪种上下文，处理层为每种上下文提供独立的实现。这样，组合数虽然还是那么多，但每个组合的处理逻辑是隔离的，改一个不会影响另一个。
2.2 条件分支隐藏的三种隐性成本
条件分支的成本不只是“代码看起来乱”。它至少带来三种隐性成本，这些成本在项目初期不明显，但会随着时间累积。
第一种是认知成本。当新人阅读一段有 20 个分支的代码时，他需要在脑子里维护一个“当前处于哪个分支”的状态，同时理解每个分支的意图。这比阅读线性代码累得多。认知成本高直接导致两个后果：新人上手慢，老人改代码时容易漏掉分支。
第二种是测试成本。每个分支都需要至少一个测试用例覆盖，分支组合还需要集成测试。分支越多，测试矩阵越大。更麻烦的是，当分支逻辑嵌套时，测试用例的设计会变得非常复杂，很多边界情况根本测不到。
第三种是演化成本。当需求变化时，如果新需求恰好落在某个已有分支的“缝隙”里，你就需要新增分支或者修改分支条件。修改分支条件往往意味着要重新验证所有受影响的组合，这个验证成本可能远高于写代码本身。
context-mode 通过“模式隔离”来降低这三种成本。每个 mode 是独立的，认知负担被限制在单个 mode 内；每个 mode 可以独立测试，测试矩阵被拆解；新增需求通常只需要新增一个 mode，不需要修改已有 mode。
2.3 一个反直觉的结论：模式越多，系统反而越简单
刚接触 context-mode 的人会有一个疑问：把逻辑拆成多个 mode，文件数量变多了，系统不是更复杂了吗？这个疑问很合理，但结论恰恰相反。
判断系统复杂度的标准不是“文件数量”，而是“任意一次修改需要理解的范围”。在条件分支方案里，修改一个行为可能需要理解整个函数的所有分支，因为分支之间可能共享变量、互相影响。在 context-mode 方案里，修改一个行为通常只需要理解对应的那个 mode 文件，因为 mode 之间是隔离的。
换句话说，context-mode 用“文件数量的增加”换取了“单次修改理解范围的缩小”。在大型项目里，后者带来的收益远大于前者。我自己的经验是，当一个模块的条件分支超过 10 个时，就应该考虑引入 context-mode 了。超过 20 个还不拆，后面基本就是维护噩梦。
3. context-mode 的核心结构：识别层、模式层与委托层
3.1 识别层：上下文从哪里来
识别层的职责是回答一个问题：当前处于什么上下文。这个问题的答案可能来自多个来源，常见的有以下几类。
第一类是运行时环境。比如浏览器里可以通过navigator.userAgent判断平台，Node.js 里可以通过process.platform判断操作系统，移动端可以通过系统 API 判断设备类型。这类信息的特点是“启动时就确定，运行中不变”。
第二类是用户配置。比如用户选择的主题、语言、权限等级。这类信息的特点是“可能变化，但变化频率低”，通常通过配置中心或本地存储读取。
第三类是实时状态。比如网络是否在线、当前页面是否可见、是否有未读消息。这类信息的特点是“变化频繁”，通常需要监听事件来更新。
第四类是业务上下文。比如当前处于哪个业务流程、上一步操作是什么、用户意图是什么。这类信息最复杂，往往需要结合多个信号综合判断。
识别层的设计要点是：把识别逻辑集中管理，不要散落在各处。我见过很多项目，判断平台的代码在十个文件里各写一遍，结果某天要新增一个平台时，漏改了一处就出 bug。正确的做法是提供一个统一的resolveContext()函数，所有需要上下文的地方都调它。
// 识别层示例：集中管理上下文解析 function resolveContext() { const platform = detectPlatform(); const role = getUserRole(); const network = navigator.onLine ? 'online' : 'offline'; return { platform, role, network, key: `${platform}:${role}:${network}` }; }注意最后那个key字段。它是上下文的唯一标识，用于在模式层里查找对应的 mode。key 的设计很关键，它决定了模式的粒度。key 太粗，模式不够精细；key 太细，模式数量爆炸。我的经验是，key 只包含“会导致行为差异”的维度，不包含“仅用于展示”的维度。
3.2 模式层：每个 mode 应该包含什么
模式层是 context-mode 的核心。每个 mode 是一个独立的对象或类，封装了该上下文下的全部行为。一个设计良好的 mode 应该包含以下几部分。
行为方法。这是 mode 的主要部分，定义了在该上下文下“做什么”。比如一个渲染 mode 可能包含renderHeader()、renderBody()、renderFooter()等方法。
配置数据。有些行为差异不是逻辑差异，而是数据差异。比如不同平台的超时时间不同、不同角色的默认页不同。这些数据应该作为 mode 的属性，而不是硬编码在方法里。
能力声明。mode 应该声明自己支持哪些能力，这样主流程可以在调用前检查能力，避免调用不存在的方法。这在多端适配场景里特别有用。
生命周期钩子。如果 mode 需要在切换时做一些初始化或清理工作，应该提供onEnter()和onExit()钩子。
// 模式层示例：一个移动端 mode const mobileMode = { name: 'mobile', // 配置数据 config: { timeout: 5000, pageSize: 10, gestureEnabled: true }, // 能力声明 capabilities: ['touch', 'gesture', 'camera'], // 行为方法 renderHeader() { return '<header class="mobile-header">...</header>'; }, renderBody(data) { return `<div class="mobile-list">${data.map(renderItem).join('')}</div>`; }, // 生命周期 onEnter() { document.body.classList.add('mobile-mode'); }, onExit() { document.body.classList.remove('mobile-mode'); } };这里有个容易忽略的点：mode 之间不应该互相引用。如果 mobileMode 里调用了 desktopMode 的方法，那隔离性就被破坏了。公共逻辑应该抽到 core 层，由 mode 调用 core，而不是 mode 调用 mode。
3.3 委托层：主流程如何与 mode 交互
委托层是连接主流程和模式层的桥梁。它的职责是：根据识别层提供的上下文，找到对应的 mode，把调用委托给它。
最简单的委托实现是一个映射表：
const modeRegistry = { 'mobile:guest:online': mobileGuestMode, 'mobile:user:online': mobileUserMode, 'desktop:guest:online': desktopGuestMode, // ... }; function getMode(context) { return modeRegistry[context.key] || defaultMode; }但实际项目里，上下文组合可能很多，不可能为每个组合都写一个 mode。这时候需要引入模式继承或模式组合机制。
模式继承是指：定义一个基础 mode，其他 mode 继承它并覆盖部分行为。比如mobileMode继承baseMode，只覆盖移动端特有的方法。这样，当 baseMode 新增一个方法时，所有 mode 自动获得。
模式组合是指：把 mode 拆成多个维度，每个维度独立定义，运行时组合。比如“平台 mode”和“角色 mode”分开定义，最终行为是两者的组合。这种方式更灵活，但实现复杂度也更高。
我的建议是：优先用继承，继承解决不了再用组合。继承的实现简单，调试也容易。组合虽然灵活，但容易出现“组合爆炸”和“方法冲突”问题。
委托层还有一个重要职责：处理 mode 不存在的情况。当上下文没有对应的 mode 时，应该有一个明确的降级策略。可以是回退到默认 mode，可以是抛出错误，也可以是动态创建一个临时 mode。这个策略要根据业务场景选择，不能含糊。
4. 落地实操：从零搭建一个 context-mode 架构
4.1 第一步：梳理上下文维度，画出组合矩阵
动手写代码之前，先做一件事：把所有会导致行为差异的上下文维度列出来，画出组合矩阵。这一步看起来简单，但很多人跳过它直接写代码，结果写到一半发现维度没理清，返工成本很高。
具体做法是：拿一张纸或者打开表格工具，列出所有维度，每个维度列出所有取值，然后计算组合数。如果组合数在 20 以内，可以接受；如果超过 50，就要考虑合并维度或者引入组合机制。
| 维度 | 取值 | 是否影响行为 |
|---|---|---|
| 平台 | iOS / Android / Web | 是 |
| 角色 | 游客 / 普通用户 / VIP | 是 |
| 网络 | 在线 / 离线 | 是 |
| 主题 | 浅色 / 深色 | 否（仅样式） |
上面这个例子里，主题维度不影响行为，只影响样式，所以不应该进入 context-mode 的 key。把它排除后，组合数是 3×3×2=18，可以接受。
4.2 第二步：定义 mode 接口，先写空实现
维度理清后，下一步是定义 mode 的接口。接口定义了“一个 mode 必须提供哪些方法”，这是所有 mode 的契约。
我的习惯是：先写接口，再写空实现，最后填逻辑。空实现的好处是，你可以先把整个架构跑通，确认委托层、识别层都能正常工作，再逐个 mode 填逻辑。这样避免了“写了一半发现架构有问题”的尴尬。
// 定义 mode 接口 class BaseMode { get name() { throw new Error('must implement name'); } get capabilities() { return []; } renderHeader() { return ''; } renderBody(data) { return ''; } renderFooter() { return ''; } onEnter() {} onExit() {} } // 空实现 class MobileMode extends BaseMode { get name() { return 'mobile'; } renderHeader() { return ''; } renderBody(data) { return ''; } }4.3 第三步：实现识别层，确保上下文可观测
识别层的实现要点是可观测。什么意思？就是当上下文判断出错时，你能快速定位是哪一步判断错了。
我的做法是在识别层加日志，记录每个维度的判断结果和最终 key。开发阶段打开日志，生产环境关闭。这样出问题时，看一眼日志就知道上下文是什么，不用猜。
function resolveContext(options = {}) { const { debug = false } = options; const platform = detectPlatform(); const role = getUserRole(); const network = navigator.onLine ? 'online' : 'offline'; const key = `${platform}:${role}:${network}`; if (debug) { console.log('[context-mode] resolved:', { platform, role, network, key }); } return { platform, role, network, key }; }另外，识别层应该支持手动覆盖。测试时经常需要模拟特定上下文，如果只能靠改环境变量来模拟，效率很低。提供一个overrideContext()方法，测试时直接指定上下文，会方便很多。
4.4 第四步：实现委托层，处理 mode 缺失与切换
委托层的核心是getMode()和switchMode()两个方法。getMode()根据上下文查找 mode，switchMode()在上下文变化时切换 mode。
切换 mode 时有一个容易忽略的点：旧 mode 的清理和新 mode 的初始化顺序。正确的顺序是：先调用旧 mode 的onExit()，再调用新 mode 的onEnter()。如果顺序反了，可能会出现资源冲突。
let currentMode = null; function switchMode(newContext) { const newMode = getMode(newContext); if (currentMode === newMode) return; if (currentMode) { currentMode.onExit(); } currentMode = newMode; currentMode.onEnter(); return currentMode; }还有一个细节：mode 切换应该是幂等的。如果连续两次切换到同一个 mode，第二次应该直接返回，不做任何操作。上面的if (currentMode === newMode) return;就是做这个的。
4.5 第五步：写测试，重点测边界和降级
context-mode 的测试重点不是“每个 mode 的逻辑对不对”，而是“上下文识别对不对”和“降级策略对不对”。
上下文识别的测试要覆盖所有维度组合，确保每个组合都能解析出正确的 key。降级策略的测试要覆盖“mode 不存在”的情况，确保系统不会崩溃。
describe('context-mode', () => { test('resolves mobile guest online', () => { mockPlatform('mobile'); mockRole('guest'); mockNetwork(true); expect(resolveContext().key).toBe('mobile:guest:online'); }); test('falls back to default mode when no match', () => { const mode = getMode({ key: 'unknown:unknown:unknown' }); expect(mode.name).toBe('default'); }); });测试覆盖率不用追求 100%，但识别层和委托层的核心路径必须覆盖。这两个地方出问题，影响面最大。
5. 踩坑实录：context-mode 落地时最容易翻车的五个地方
5.1 坑一：key 设计过细导致模式爆炸
我见过一个项目，key 里包含了“用户 ID”这个维度。结果每个用户都对应一个独立的 mode，模式数量随用户数增长。这显然是把“上下文”和“实例”搞混了。
key 里应该只包含会导致行为差异的、取值有限的维度。用户 ID 取值无限，不应该进 key。如果确实需要针对特定用户做差异化，应该用配置覆盖机制，而不是新增 mode。
判断一个维度该不该进 key，问自己一个问题：这个维度的取值数量是有限的吗？如果是有限的（比如平台只有三种），可以进 key；如果是无限的（比如用户 ID、时间戳），不能进 key。
5.2 坑二：mode 之间共享可变状态
这是最隐蔽的坑。两个 mode 看起来是独立的，但它们引用了同一个可变对象，一个 mode 修改了对象，另一个 mode 读到了脏数据。
// 错误示例：共享可变配置 const sharedConfig = { timeout: 5000 }; const modeA = { config: sharedConfig, doSomething() { this.config.timeout = 3000; } }; const modeB = { config: sharedConfig, doSomething() { console.log(this.config.timeout); } // 可能读到 3000 };解决办法是：每个 mode 的配置必须是独立的，不能共享引用。如果确实需要共享只读数据，用Object.freeze()冻结，防止意外修改。
5.3 坑三：切换 mode 时忘记清理副作用
mode 的onEnter()里注册了事件监听、启动了定时器、修改了全局样式，但onExit()里忘记清理。结果切换几次后，事件监听器堆了一堆，定时器跑了一堆，全局样式被改得乱七八糟。
我的经验是：onEnter()里做的每一件事，都要在onExit()里有对应的清理。写onEnter()的时候，顺手把onExit()的清理代码也写了，不要留到后面补。后面补的时候，十有八九会漏。
const mode = { onEnter() { this.handler = () => { /* ... */ }; window.addEventListener('resize', this.handler); this.timer = setInterval(() => { /* ... */ }, 1000); }, onExit() { window.removeEventListener('resize', this.handler); clearInterval(this.timer); this.handler = null; this.timer = null; } };5.4 坑四：降级策略不明确导致静默失败
当上下文没有对应 mode 时，如果直接返回null或者undefined，调用方可能会在某个深处报错，排查起来很困难。更糟的是，如果调用方做了空值检查，可能会静默失败，用户看到的是空白页面，但控制台没有任何错误。
正确的做法是：降级策略必须显式且可观测。要么回退到默认 mode 并打日志，要么抛出明确的错误。不要返回null让调用方自己处理。
function getMode(context) { const mode = modeRegistry[context.key]; if (!mode) { console.warn(`[context-mode] no mode for key: ${context.key}, falling back to default`); return defaultMode; } return mode; }5.5 坑五：过度设计，为不存在的场景提前抽象
最后一个坑是反向的：有些人学了 context-mode 之后，恨不得所有地方都用。一个只有两种状态的开关，也要拆成两个 mode。这就是过度设计。
context-mode 适合的场景是：上下文维度多、组合多、行为差异大。如果只有一两个维度，或者行为差异很小，用简单的条件分支就够了。抽象是有成本的，只有当抽象带来的收益大于成本时，才值得做。
我的判断标准是：当条件分支超过 10 个，或者同一个判断在三个以上地方重复出现时，才考虑引入 context-mode。低于这个阈值，条件分支更直接、更好维护。
6. 从 Web 到 AI 应用：context-mode 的跨领域迁移思路
6.1 在 CLI 工具里的应用：交互模式切换
context-mode 的思路不限于 Web 前端。我在做一个命令行工具时，用类似的思路处理了“交互模式”和“批处理模式”的切换。
交互模式下，工具需要实时读取用户输入、显示进度条、支持快捷键。批处理模式下，工具需要静默运行、输出结构化日志、支持管道输入。这两种模式的行为差异很大，如果用一个函数处理，会充满if (isInteractive)判断。
用 context-mode 重构后，交互模式和批处理模式各自成为一个 mode，主流程只负责根据参数判断用哪个 mode。新增“守护进程模式”时，只需要新增一个 mode 文件，主流程一行不用改。
6.2 在 AI 对话系统里的应用：上下文窗口管理
AI 对话系统里有一个经典问题：对话历史越来越长，超出模型上下文窗口怎么办？常见的做法是截断、摘要、或者滑动窗口。但不同场景下，合适的策略不同。
比如客服场景下，最近的对话最重要，适合滑动窗口；文档问答场景下，文档内容最重要，对话历史可以压缩；多轮任务场景下，任务相关的历史不能丢，无关的可以丢。
这其实就是 context-mode 的思路：根据对话的上下文类型，选择不同的历史管理策略。每个策略是一个 mode，系统根据当前对话的类型切换到对应 mode。这样，新增一种对话类型时，只需要新增一个历史管理 mode。
6.3 在构建工具里的应用：多目标构建模式
现代构建工具经常需要支持多种构建目标：开发构建、生产构建、测试构建、SSR 构建……每种目标的配置差异很大。如果用一个配置文件加一堆条件判断，会非常难维护。
用 context-mode 的思路，每种构建目标对应一个 mode，mode 里定义该目标的全部配置。构建工具根据命令行参数选择 mode，然后执行构建。新增构建目标时，新增一个 mode 文件即可。
这种思路在 Vite、Rollup 这些工具里其实已经有体现，只是没有明确叫 context-mode。理解了这个思路，你在配置这些工具时会更清楚为什么它们的配置文件要那样组织。
6.4 迁移时的通用原则：识别、隔离、委托
不管在哪个领域应用 context-mode，核心步骤都是一样的：识别上下文、隔离模式、委托调用。
识别上下文的关键是找到“会导致行为差异的维度”，并确保这些维度可观测、可覆盖。隔离模式的关键是确保 mode 之间不共享可变状态，每个 mode 可以独立测试。委托调用的关键是处理 mode 缺失的情况，确保降级策略明确。
这三步看起来简单，但每一步都有细节。识别上下文时容易把“实例”当成“上下文”，隔离模式时容易共享状态，委托调用时容易忽略降级。这些坑我在前面都讲过，迁移到新领域时同样适用。
7. 我个人的几条实操建议
第一条建议：先写测试，再写 mode。context-mode 的架构决定了 mode 之间是隔离的，这意味着你可以先写测试定义 mode 的行为，再实现 mode。测试驱动的方式在这里特别有效，因为每个 mode 的边界很清晰，测试写起来很自然。
第二条建议：mode 的命名要体现上下文，不要体现行为。比如mobileMode比touchMode好，因为“移动端”是上下文，“触摸”是行为。上下文可能对应多种行为，用行为命名会限制 mode 的职责范围。
第三条建议：定期审查 mode 的数量和相似度。如果两个 mode 有 80% 的代码相同，说明抽象层次不对，应该提取公共部分。如果 mode 数量超过 20 个，说明 key 设计可能过细，需要合并维度。
第四条建议：给 mode 加版本号。当 mode 的行为发生不兼容变化时，版本号可以帮助你平滑迁移。比如mobileModeV2和mobileModeV1并存一段时间，逐步切换。
第五条建议：不要为了用而用。context-mode 是一个工具，不是目的。如果一个模块用条件分支就能清晰表达，就不要强行拆 mode。判断标准很简单：拆了之后，单次修改需要理解的范围缩小了吗？如果没缩小，说明拆得不对。
最后分享一个我在实际项目里总结的小技巧：给每个 mode 写一句“一句话描述”，放在 mode 文件的顶部注释里。这句话描述“这个 mode 在什么上下文下、做什么事”。当 mode 数量多了之后，这句话能帮你快速回忆每个 mode 的职责，比看代码快得多。
/** * mobileMode - 移动端在线用户模式 * 上下文：platform=mobile, role=user, network=online * 职责：渲染移动端布局，启用触摸手势，使用移动端优化配置 */ const mobileMode = { /* ... */ };这个习惯看起来不起眼，但在 mode 数量超过 10 个之后，价值就体现出来了。新人接手时，扫一遍所有 mode 的一句话描述，就能对系统有个整体认知，不用逐个读代码。
