企业官网建设流程全解析

做 CLI 工具和本地开发工具链的同行大概都有过这种体验：新起一个项目，目录结构、参数解析、日志格式、配置读取、错误码、缓存路径这些事，前三个月写得飞快，到第六个月开始互相打架，到第二年基本没人敢动。witty-opencode这个基础包就是在这个背景下折腾出来的东西——它本身不实现任何业务功能，只负责把“每个工具都要写一遍、每次都写得不一样”的那批底层能力收拢成一套约定。十个关键功能覆盖了入口注册、分层配置加载、配置校验兜底、结构化日志、错误包装与退出码、路径解析、生命周期钩子、扩展加载、本地缓存、自检诊断。配置管理是它最重的一块，也是最多人第一次接入时踩坑的地方。这篇内容适合两类人看：正在自研脚手架、想少走弯路的工具链开发者，以及接手了一个“历史包袱型”CLI 项目、需要把配置体系理清楚的中高级工程师。下面全部是我在实际接入和二次开发过程中的拆解，含代码、含参数取值逻辑、含踩坑记录。

1. 先想清楚：基础包的边界到底在哪

动手写基础包之前，最容易犯的错误是把它做成一个“万能框架”。我见过好几个类似的东西，一开始雄心勃勃要统一整个研发流程，结果半年后变成一个谁都不敢删、谁都不敢改的黑盒。witty-opencode在设计上刻意收得很紧，这个取舍值得展开说。

1.1 为什么基础包不该碰业务逻辑

基础包和业务包的分界线，我的判断标准只有一条：这段代码会不会因为业务需求变化而变化。会变的，一律不进基础包。

举个具体的例子。日志模块，基础包只做三件事：定义日志级别枚举、定义输出格式（JSON 行格式或人类可读格式二选一）、提供一个全局的 logger 实例获取入口。至于“哪些事件需要打日志”“日志里要带哪些业务字段”，全部交回业务侧。反过来，如果基础包里写了“请求成功时打印 xxx”这种逻辑，那它就已经越界了。

这个边界听起来简单，实际落地时诱惑很多。比如“顺便”提供一个 HTTP 请求封装，因为每个工具都要调接口；“顺便”提供一个重试策略，因为每个工具都要处理网络抖动。这些“顺便”累积起来，基础包的依赖树会迅速膨胀，最终导致升级基础包时，你等于在升级半个技术栈，风险完全不可控。

我现在的做法是：基础包只依赖 Node 内置模块加上极少数零依赖的工具库（路径处理、深合并这类），任何带副作用的第三方依赖都通过“可选 peer 依赖”的形式暴露，由业务侧决定装不装。

注意：判断一个能力该不该进基础包，还有一个反向检验法——如果这个能力删掉之后，业务侧只需要多写 20 行代码就能补上，那它就不该进基础包。基础包的价值在于消除“重复且容易写错”的部分，不在于消除“重复但很简单”的部分。

1.2 十个关键功能的分层逻辑

十个功能不是平铺的，它们在运行时是有依赖顺序的。我按启动链路把它们分成三层，这个分层直接决定了后面配置加载的时机设计。

这个表看着简单，但“路径解析必须在配置加载之前”这一条，我最初是反着做的——先读配置，配置里再指定数据目录。结果就是配置文件本身的位置没法由配置决定，陷入循环依赖。后来改成：先用系统默认规则算出配置目录，读完配置之后如果配置里覆盖了数据目录，再更新运行期的路径对象。这个顺序调整花了我大概两天，但把后面所有跟路径相关的诡异问题一次性解决了。

分层还有一个隐性好处：每一层都能单独测试。引导层不依赖配置内容，校验层不依赖日志输出，运行层不依赖具体命令。写单测的时候不用 mock 一整个进程，覆盖率和可维护性都好很多。

2. 十个关键功能逐个拆开看

这一节把十个功能按启动顺序过一遍，每个都说说它到底解决什么问题、实现上容易在哪儿翻车。代码示例用 TypeScript，逻辑本身跟语言无关，换成其他语言思路一致。

2.1 功能一：统一入口与命令注册

命令注册看着是最没技术含量的部分，但它决定了后面九个功能能不能顺利挂上去。witty-opencode的入口只做一件事：解析出“用户想执行哪个命令”，然后把控制权交给对应命令，自己不再参与后续逻辑。

// src/entry.ts import { CommandRegistry } from './registry'; const registry = new CommandRegistry(); registry.register({ name: 'build', aliases: ['b'], description: '构建产物', options: [ { flag: '--out', type: 'string', default: 'dist' }, { flag: '--minify', type: 'boolean', default: false }, ], handler: async (ctx) => { await runBuild(ctx); }, }); registry.register({ name: 'doctor', description: '运行环境自检', handler: async (ctx) => reportDiagnostics(ctx), }); await registry.dispatch(process.argv.slice(2));

关键设计点在dispatch里。它做了三件事：第一，遇到未知命令时不要直接抛异常，而是打印可用命令列表并以退出码 2 结束；第二，命令别名解析要在参数解析之前做，否则-b这种短别名会被当成参数；第三，全局参数（--config、--verbose、--no-color）要在分发之前剥离出来，避免每个命令都要重复声明一遍。

第三点我踩过坑。最初全局参数是每个命令自己解析的，结果某个命令忘了支持--verbose，用户加上这个参数之后直接报“未知参数”。改成入口层剥离全局参数、把结果写进一个共享的GlobalOptions对象之后再分发，问题消失。代价是全局参数和命令参数有重名时要定规则，我的做法是：全局参数永远优先，同名的命令参数直接在校验阶段报错，不搞“就近覆盖”这种模糊逻辑。

实操心得：命令注册表用 Map 而不是数组存，查询是 O(1)。但遍历打印帮助时要注意 Map 保持插入顺序，所以注册顺序就是帮助里的显示顺序，把高频命令放前面。

2.2 功能二：分层配置加载的优先级设计

这是整个基础包最核心的部分，后面单独用一大章讲配置管理，这里先说加载机制本身。

witty-opencode采用五层配置，优先级从低到高：

1. 内置默认值（写死在代码里的defaults对象）
2. 用户级配置（~/.config/<name>/config.json）
3. 项目级配置（项目根目录的.wittyrc.json或witty.config.json）
4. 环境变量（约定前缀转换，如WITTY_HTTP_TIMEOUT=5000）
5. 命令行参数（--http.timeout 5000）

合并策略是深合并而不是浅覆盖，但对数组的处理有特殊约定：数组默认整体替换，不拼接。这个选择是有意为之的。早期版本用拼接，结果用户想覆盖掉默认的exclude列表，发现怎么删都删不干净，只能把默认值一个个复制过来再排除，体验极差。改成整体替换之后，语义清晰了，代价是用户想“追加一项”时必须把原有的都写出来——但至少这是可预期行为。

实现上深合并要处理四个边界情况：值为undefined时跳过、值为null时视为显式清空、对象递归合并、其余类型直接赋值。null这一条尤其重要，没有它用户没法把某个默认开启的布尔配置关掉（false会被误判为未设置的情况在某些实现里很常见）。

2.3 功能三：配置校验与默认值兜底

配置读进来了，不代表能用。我做过的项目里，出问题最多的不是“配置读不到”，而是“配置读到了但类型不对”，比如端口写成了字符串"8080"、超时写成了"5s"这种带单位的字符串。这类错误如果等到运行到一半才发现，排查成本极高。

所以校验必须提前到启动阶段，而且要一次性把所有问题都报出来，不能“发现一个抛一个”。这里我用一份轻量的 schema 声明，不引入重量级校验库：

export const configSchema = { http: { timeout: { type: 'number', min: 100, max: 300000, default: 30000 }, retries: { type: 'number', min: 0, max: 10, default: 2 }, baseUrl: { type: 'string', pattern: /^https?:\/\//, required: true }, }, log: { level: { type: 'enum', values: ['debug', 'info', 'warn', 'error'], default: 'info' }, format: { type: 'enum', values: ['json', 'pretty'], default: 'pretty' }, }, cache: { enabled: { type: 'boolean', default: true }, ttl: { type: 'number', min: 0, default: 3600 }, dir: { type: 'string' }, }, };

校验器遍历这份声明，逐项比对实际值，收集所有错误后统一抛出。错误信息里必须带上完整路径（比如http.timeout而不是timeout）和实际收到的值，这两个信息缺一个，用户都要多花十分钟定位。

默认值兜底和校验放在一起做，顺序是：先合并，再校验，校验通过后把缺失项填上默认值，最后冻结整个配置对象。冻结这一步很关键——我在一个项目里遇到过配置对象被某个中间件偷偷改掉，导致后续逻辑行为不一致，查了整整一下午。Object.freeze是深冻结的话要自己写递归，浅冻结解决不了嵌套对象的问题。

2.4 功能四：结构化日志的分级与输出格式

日志这块，基础包只提供能力，不制定策略。具体来说提供三样东西：级别判断、字段注入、格式切换。

级别判断的逻辑是“当前级别 <= 配置级别才输出”，这个比较用数字权重实现，避免字符串比较出错。字段注入指的是每条日志自动带上ts（时间戳）、level、pid、cmd（当前命令名）这几个公共字段，业务侧只需要传自己的字段。

格式切换提供两种输出：json模式一行一条，机器解析友好；pretty模式带颜色和缩进，终端里看舒服。切换依据优先级是：命令行--log.format> 环境变量 > 配置文件 > 默认值。另外还要检测process.stdout.isTTY，非 TTY 环境（比如 CI 里重定向到文件）自动降级成json，避免颜色控制字符污染日志文件。

export function createLogger(opts: LoggerOptions) { const weights = { debug: 10, info: 20, warn: 30, error: 40 }; const threshold = weights[opts.level]; const emit = (level: keyof typeof weights, msg: string, fields?: Record<string, unknown>) => { if (weights[level] < threshold) return; const record = { ts: new Date().toISOString(), level, pid: process.pid, cmd: opts.cmd, msg, ...fields }; const line = opts.format === 'json' ? JSON.stringify(record) : prettyFormat(record); (level === 'error' ? process.stderr : process.stdout).write(line + '\n'); }; return { debug: (m: string, f?: Record<string, unknown>) => emit('debug', m, f), info: (m: string, f?: Record<string, unknown>) => emit('info', m, f), warn: (m: string, f?: Record<string, unknown>) => emit('warn', m, f), error: (m: string, f?: Record<string, unknown>) => emit('error', m, f), }; }

注意error级别写stderr这个细节。很多工具把所有日志都写stdout，导致用户cmd > result.json的时候结果文件里混进了日志，下游解析直接崩。规矩是：业务输出走 stdout，日志和错误走 stderr，这条守住了，工具的可组合性就保住了。

2.5 功能五：错误包装与退出码约定

退出码是 CLI 工具的“返回值”，但很多工具随便用，导致脚本里没法根据退出码做分支。witty-opencode定了一套最小约定：

错误包装的核心是一个WittyError类，构造函数接收三个参数：用户可读消息、机器可读 code、可选的原错误对象。内部保留cause链，输出时根据日志级别决定展开多少——debug级别打完整堆栈，info级别只打消息和 code，避免把堆栈糊到普通用户脸上。

另一个细节是“错误消息要告诉用户下一步做什么”。写“配置文件校验失败”是没用的，要写“http.baseUrl必须是 http 或 https 开头的地址，当前值为ftp://...，请检查.wittyrc.json第 12 行”。多花十秒写清楚，能省掉用户十分钟的猜测。

2.6 功能六：路径与目录解析的跨平台处理

路径问题是那种“在开发机上永远没问题、换台机器就炸”的经典分类。基础包需要处理四类路径：配置目录、数据目录、缓存目录、日志目录。规则上参考操作系统的通用约定（Linux 走XDG_CONFIG_HOME那一套，macOS 走~/Library/Application Support，Windows 走%APPDATA%），但不要自己硬编码，直接用内置的os.homedir()加上条件判断。

export function resolvePaths(appName: string) { const home = os.homedir(); const platform = process.platform; const configBase = process.env.XDG_CONFIG_HOME ?? (platform === 'win32' ? process.env.APPDATA : path.join(home, platform === 'darwin' ? 'Library/Application Support' : '.config')) ?? path.join(home, '.config'); const cacheBase = process.env.XDG_CACHE_HOME ?? (platform === 'win32' ? process.env.LOCALAPPDATA : path.join(home, platform === 'darwin' ? 'Library/Caches' : '.cache')) ?? path.join(home, '.cache'); return { config: path.join(configBase, appName), cache: path.join(cacheBase, appName), data: path.join(home, platform === 'darwin' ? 'Library/Application Support' : '.local/share', appName), log: path.join(cacheBase, appName, 'logs'), }; }

两个坑必须提。第一，Windows 上%APPDATA%理论上一定存在，但某些精简环境或容器里确实没有，所以必须有一层??兜底。第二，路径拼接一律用path.join而不是字符串拼接，path.join会处理多余的斜杠和分隔符差异，手写base + '/' + name在 Windows 上虽然 Node 大多能容忍，但输出到日志里会很难看，也不利于后续做路径比较。

第三个坑是权限。拿到路径之后要检测目录是否可写，不可写时不能直接崩，要回退到系统临时目录并打一条 warn 日志。这个回退逻辑在 CI 环境和只读容器里救过我好几次。

2.7 功能七：生命周期钩子的触发顺序

钩子解决的是“扩展点”问题。命令执行前后需要插逻辑，比如“执行前检查登录态”“执行后清理临时文件”。基础包定义了四个钩子点：beforeParse、afterConfig、beforeRun、afterRun。

触发顺序是严格串行的，beforeRun这类前置钩子任何一个抛出异常都会中断主流程，afterRun这类后置钩子则全部执行完再汇总异常——这个区别很重要。前置钩子失败说明前置条件不满足，继续往下跑没意义；后置钩子失败往往只是清理没做完，不该影响已经完成的主任务结果。

async function runWithHooks(ctx: Context, handler: Handler) { for (const hook of ctx.hooks.beforeRun) { await hook(ctx); // 前置：抛错即中断 } let result: unknown; let mainError: unknown; try { result = await handler(ctx); } catch (e) { mainError = e; } const hookErrors: unknown[] = []; for (const hook of ctx.hooks.afterRun) { try { await hook(ctx, result); } catch (e) { hookErrors.push(e); // 后置：收集不中断 } } if (mainError) throw mainError; if (hookErrors.length) ctx.logger.warn('后置钩子存在失败', { count: hookErrors.length }); return result; }

钩子注册顺序决定执行顺序，这点要写进文档。有人会想当然认为“后注册的先执行”（像某些中间件模型那样），但这里用的是直白的先进先出。理由是钩子之间往往有依赖关系，先进先出符合阅读顺序，容易推理。

2.8 功能八：扩展加载的失败隔离

扩展加载的关键词是隔离。某个扩展加载失败，不能把整个工具带崩。实现上逐个require/import，用 try-catch 包住，失败的记录到诊断信息里，继续加载下一个。

扩展的发现机制有两种：显式声明（配置文件里的plugins数组）和约定目录扫描（用户级扩展目录）。我倾向显式声明优先，因为隐式扫描在扩展数量多了之后启动变慢，而且用户很难搞清楚“为什么这个扩展被加载了”。扫描保留，但默认关闭，通过配置项plugins.autoScan打开。

加载顺序同样按声明顺序串行。并发加载虽然快，但扩展之间可能有依赖（A 扩展注册的钩子 B 扩展要用），并发会让顺序变得不确定。扩展加载本来就不是性能瓶颈，串行的确定性更值钱。

注意：扩展模块的import一定要用动态导入，并且路径要经过pathToFileURL转换。在 Windows 上直接拼接file://前缀，如果路径里带空格或中文，很容易失败。

2.9 功能九：本地缓存与失效策略

缓存部分提供一个极简的键值存储，落盘为单个 JSON 文件（或者按 key 哈希分片成多个文件），带 TTL。三个约定：

• 键是字符串，值是任意可 JSON 序列化的对象
• 读取时校验 TTL，过期视为不存在，并异步清理
• 写入用“写临时文件 + 原子重命名”，避免进程中断导致缓存文件损坏

原子写入这一步很多人省掉，直到某次进程被 kill 之后缓存文件变成半截 JSON，下次启动直接解析失败。实现很简单：

async function writeAtomic(file: string, data: unknown) { const tmp = `${file}.${process.pid}.${Date.now()}.tmp`; await fs.promises.writeFile(tmp, JSON.stringify(data), 'utf8'); await fs.promises.rename(tmp, file); }

rename在同一文件系统内是原子操作，这就是为什么要让临时文件和目标文件在同一个目录下。放到os.tmpdir()再 rename 跨文件系统会失败，这个小细节我踩过一次。

缓存损坏的处理策略也要明确：解析失败时不要抛异常，直接当成空缓存，删掉旧文件重建。缓存是加速手段，不是数据源，为它报错中断主流程是本末倒置。

2.10 功能十：自检与诊断命令

doctor命令是这套东西里性价比最高的一个功能。它做的事情很朴素：把配置、路径、权限、扩展加载情况、缓存状态全部检查一遍，输出一份表格。

检查项包括：配置文件是否存在及解析结果、每一层配置的贡献、最终生效配置的完整快照（敏感字段脱敏）、各目录是否存在及可写、扩展加载成功/失败列表、缓存文件大小与条目数、运行时版本与环境信息。

$ witty-opencode doctor [配置] 默认值层 ok 12 项 用户级配置 ok ~/.config/witty-opencode/config.json 项目级配置 缺失 ./.wittyrc.json 环境变量 ok 3 项覆盖 命令行参数 无 [目录] 配置目录 ok 可写 缓存目录 ok 可写，当前 42 个条目 / 1.2 MB 日志目录 警告 不可写，已回退到临时目录 [扩展] alpha-tool ok beta-tool 失败 MODULE_NOT_FOUND [结论] 1 个警告，1 个错误

用户报问题时第一句话往往是“它跑不起来”，你让他跑一次doctor把输出贴过来，八成问题当场就能定位。这个功能我建议所有自研工具都做，投入产出比极高。

3. 配置管理：分层、合并与校验的完整方案

十个功能里有三个直接跟配置相关，配置管理值得单独展开。这一章讲清楚分层怎么设计、合并怎么实现、校验怎么做才能让用户少骂人。

3.1 分层优先级背后的取舍

前面提了五层优先级，这里说说为什么是这个顺序，以及哪些顺序是不能变的。

默认值在最底层没有争议。用户级配置比项目级配置低，这个选择有讨论空间——有些工具反过来，认为项目级是“基础设定”，用户级是“个人覆盖”。我的判断依据是作用域越窄优先级越高：项目级配置只影响当前项目，意图更具体；用户级配置是全局习惯，应该作为兜底。所以项目级覆盖用户级。这条规则跟主流工具的直觉一致，用户不需要额外学习。

环境变量在配置文件之上，理由是临时性。CI 环境里改配置不可能去改文件，只能设环境变量，所以它必须能覆盖。命令行参数最高，因为它最临时、最显式，用户敲在命令行上的东西就是他这一刻想要的。

有一类特殊场景要处理：数组型配置的“追加语义”。前面说数组整体替换，但确实存在“我想在默认的忽略列表基础上再加两条”的需求。解法是提供一个显式的追加语法，比如键名加+前缀：

{ "+exclude": ["node_modules/.cache", "*.log"] }

合并器看到+前缀就做拼接，看到普通键名就做替换。这个语法第一次见到会有点意外，但写在文档里、配一条提示，用户接受度不错。关键是它把“替换”和“追加”的意图显式化了，不再靠猜。

3.2 深合并的实现细节

深合并的代码不长，但边界情况多。下面这版是我最终定稿的，处理了undefined、null、数组、普通对象四种情况：

type Plain = Record<string, unknown>; function isPlainObject(v: unknown): v is Plain { return typeof v === 'object' && v !== null && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null); } export function deepMerge(base: Plain, override: Plain): Plain { const out: Plain = { ...base }; for (const [rawKey, value] of Object.entries(override)) { if (value === undefined) continue; const isAppend = rawKey.startsWith('+'); const key = isAppend ? rawKey.slice(1) : rawKey; if (value === null) { delete out[key]; continue; } if (isAppend && Array.isArray(value)) { const prev = Array.isArray(out[key]) ? (out[key] as unknown[]) : []; out[key] = [...prev, ...value]; continue; } if (isPlainObject(value) && isPlainObject(out[key])) { out[key] = deepMerge(out[key] as Plain, value); continue; } out[key] = value; } return out; }

几个注意点。第一，isPlainObject用了原型判断而不是简单的typeof === 'object'，因为要排除Date、RegExp、Map这些。配置文件理论上都是 JSON，不该出现这些类型，但配置对象可能来自代码里的默认值，那里什么类型都可能有。第二，null的处理是删除键而不是设成null，这样下游读配置的时候拿到的就是undefined，跟“从没设置过”一致，走默认值逻辑。第三，+前缀的拼接发生在递归之前，避免前缀被带到下一层的键名里。

合并顺序就是从低优先级到高优先级依次调用：

const layers = [defaults, userConfig, projectConfig, envConfig, cliConfig]; const effective = layers.reduce((acc, layer) => deepMerge(acc, layer), {} as Plain);

这个reduce写完就一行，但每个 layer 的生成过程才是工作量所在。环境变量那层尤其麻烦，需要把WITTY_HTTP_TIMEOUT这种扁平命名转回嵌套结构。

3.3 环境变量的扁平命名转换

约定是：前缀WITTY_，后面按双下划线__分隔层级，单下划线保留给键名本身。比如：

为什么用双下划线做层级分隔？因为配置键名本身经常带下划线（base_url这种写法太常见了），单下划线做分隔会有歧义。双下划线在配置键名里几乎不会出现，冲突概率足够低。

值的类型转换也要处理。环境变量本质上全是字符串，读进来之后要按目标 schema 的类型做转换：number转数字、boolean认true/false/1/0、array按逗号切分。转换失败不能静默忽略，要报一条明确的错：“环境变量WITTY_HTTP__TIMEOUT的值abc无法转换为数字”。这类错误报得越具体越好，因为用户在 CI 里调环境变量的时候看不到任何上下文。

function coerce(raw: string, type: string): unknown { switch (type) { case 'number': { const n = Number(raw); if (Number.isNaN(n)) throw new WittyError(`无法转换为数字: ${raw}`, 'E_ENV_TYPE'); return n; } case 'boolean': if (['true', '1', 'yes'].includes(raw.toLowerCase())) return true; if (['false', '0', 'no'].includes(raw.toLowerCase())) return false; throw new WittyError(`无法转换为布尔值: ${raw}`, 'E_ENV_TYPE'); case 'array': return raw.split(',').map((s) => s.trim()).filter(Boolean); default: return raw; } }

实操心得：coerce的时候不要相信Number()的全部行为。Number('')是0，Number(' 12 ')是12，Number('0x10')是16。如果你希望只接受十进制整数，得用正则先过滤一遍。我吃过Number('')的亏——空字符串的环境变量被当成 0，把一个本该报错的配置静默变成了合法值。

3.4 校验的错误聚合与提示设计

校验器的输出质量，直接决定用户对这套工具的第一印象。我的标准是：一条错误信息要能让用户不看文档就知道怎么改。

具体来说包含四个要素：配置项的完整路径、期望的类型或约束、实际收到的值、以及最可能的修正建议。举个例子：

配置校验失败（共 3 项）： 1. http.timeout 期望: 100 到 300000 之间的数字 实际: "5s" (字符串) 建议: 如果使用带单位的写法请换算成毫秒，例如 "5s" 写成 5000 2. log.level 期望: debug | info | warn | error 之一 实际: "verbose" 建议: "verbose" 不是合法级别，最接近的是 "debug" 3. cache.dir 期望: 非空字符串 实际: "" 建议: 删除该配置项以使用默认目录，或填入绝对路径

“最接近的是 debug” 这条是用编辑距离算出来的，成本几行代码，体验提升明显。用户把verbose改成debug就通了，不用去翻文档确认有哪些级别。

校验还有一个容易忽略的点：停止条件。配置错误超过一定数量（比如 20 条）就截止输出，提示“还有 N 项错误未显示”。不设上限的话，一个结构完全错位的配置文件能刷屏几百行，反而看不清关键信息。

4. 从零搭一套可复现的配置体系

原理讲完了，这一章是操作篇。假设你手上有个新项目要接入，或者有个老项目的配置乱成一锅粥要重构，按下面的顺序走。

4.1 目录结构与文件命名约定

先定目录。我的建议是项目根的配置文件名固定为.wittyrc.json，同时接受witty.config.json作为备选。为什么不只用.xxxrc这种隐式命名？因为隐式文件在很多图形化工具里默认隐藏，新人接手时根本不知道有这么个文件。双命名给了一个平滑过渡路径：老项目沿用 rc 风格，新项目用显式的*.config.json。

用户级和项目级的完整布局：

项目根/ ├── .wittyrc.json # 项目级配置（提交进仓库） ├── .wittyrc.local.json # 本地覆盖（加入 .gitignore） └── src/ 用户目录/ └── ~/.config/witty-opencode/ ├── config.json # 用户级配置 └── config.local.json # 本机局部覆盖

.local.json这一层的设计意图是“放不该进版本库的东西”——本地路径、个人偏好、临时的调试开关。它插在对应层级之上、更高层级之下。也就是说项目级.wittyrc.local.json覆盖项目级.wittyrc.json，但不覆盖环境变量。

加这一层之后，配置文件里就不需要写任何“本机特有”的东西了，团队协作时的 diff 干净很多。这个模式很多工具都有，但命名五花八门（.local、.override、.user），我选.local是因为它最不容易被误认为“环境配置”。

4.2 配置文件的加载时机与错误边界

加载时机前面提过顺序，这里说错误边界。每一层的加载都用独立的 try-catch，语义分三种：

• 文件不存在：正常情况，视为空层，debug级别记一条
• 文件存在但 JSON 解析失败：这是真错误，必须报出来，而且要带行号
• 文件存在、解析成功、但类型不是对象：报错，因为一个数组或字符串做不了配置

JSON 解析失败带行号这件事，标准库的错误信息里其实有位置信息（不同运行时的字段名不一样），把它提取出来重新格式化一下：

function loadConfigFile(file: string): Plain { let raw: string; try { raw = fs.readFileSync(file, 'utf8'); } catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return {}; throw new WittyError(`无法读取配置文件: ${file}`, 'E_CONFIG_READ', e); } try { const parsed = JSON.parse(raw); if (!isPlainObject(parsed)) { throw new WittyError(`配置文件根节点必须是对象: ${file}`, 'E_CONFIG_SHAPE'); } return parsed; } catch (e) { if (e instanceof WittyError) throw e; throw new WittyError(`配置文件不是合法 JSON: ${file}\n${(e as Error).message}`, 'E_CONFIG_PARSE', e); } }

注意ENOENT的判断——只有“文件不存在”才返回空对象，权限不足（EACCES）或者路径是个目录（EISDIR）都该报错。有些实现图省事把所有读文件异常都当成“没配置”，结果用户把配置文件的权限设错了，工具照样跑，但跑的是默认配置，排查起来极其痛苦。

注意：JSON 里不能写注释，这是很多用户在配置文件里踩的第一个坑。如果你的工具面向非技术用户，建议支持 JSONC（带注释的 JSON）或者直接用 YAML。我这里的取舍是标准 JSON，因为解析零依赖、生态兼容性最好，代价是要在报错信息里明确提示“配置文件不支持注释”。

4.3 配置变更的追踪与回滚

配置体系上线之后，下一个问题就是“谁在什么时候改了哪一项”。尤其是用户级配置和项目级配置同时存在的时候，最终生效值到底是哪层来的，必须有办法查。

witty-opencode的做法是在配置对象上挂一个不可枚举的__meta属性，记录每一项的来源层级：

type Provenance = Record<string, 'default' | 'user' | 'user-local' | 'project' | 'project-local' | 'env' | 'cli'>; function annotate(config: Plain, source: string, meta: Provenance, prefix = '') { for (const [k, v] of Object.entries(config)) { const full = prefix ? `${prefix}.${k}` : k; if (isPlainObject(v)) { annotate(v, source, meta, full); } else { meta[full] = source as Provenance[string]; } } }

doctor命令里可以加一个--explain <key>参数，直接告诉你这个值是从哪层来的：

$ witty-opencode doctor --explain http.timeout http.timeout = 15000 来源: 环境变量 (WITTY_HTTP__TIMEOUT) 用户级配置: 30000 项目级配置: 未设置 默认值: 30000

这个输出把“为什么是这个值”讲得明明白白。有了它，配置相关的扯皮至少减少一半——不用再让用户把配置文件贴出来，让他跑一条命令就行。

回滚这块，基础包不负责版本管理，但提供一个能力：--dump-config <file>把当前生效配置导出成一份完整的 JSON。这份文件可以当成“快照”，出问题时拿来对比，或者直接作为基线配置提交。注意导出的文件必须做敏感字段脱敏，凡是键名匹配/(token|secret|password|key)/i的一律替换成***，并且要保留一个--no-redact开关（文档里标注“仅限本地使用”）。

5. 常见问题与排查技巧实录

这一章是我实际接到的反馈和自己在开发过程中遇到的问题，按出现频率排序。

5.1 高频问题速查表

这张表能覆盖大概七八成的问题。剩下的是环境特殊的，得具体看。

5.2 几个印象深刻的坑

第一个坑：process.exitCode和process.exit()的区别。

早期版本在错误处理里直接调process.exit(1)，结果日志的最后几行偶尔丢失。原因是exit()会立即终止事件循环，而 stdout 在某些情况下是异步刷盘的（尤其是管道重定向的时候）。改成设置process.exitCode = 1然后正常返回，让事件循环自己走完，问题就没了。规矩是：除非有明确理由，永远不要调process.exit()，设置exitCode就够了。如果真需要在退出前强制等待 IO，用一个显式的 flush 然后await。

第二个坑：配置冻结导致扩展无法注入默认值。

前面说配置对象校验完要深冻结，这个设计本身没问题，但扩展的加载时机在冻结之后，某些扩展需要往配置里写自己的默认值，一写就抛异常（严格模式下对冻结对象赋值会抛TypeError）。解决方案是给扩展单独开一个extensions命名空间，这个子对象在冻结时跳过，扩展只允许往这里面写。这就是典型的“约束和扩展性打架”，解法不是放弃约束，而是划一个明确的例外区域。

第三个坑：深合并把Date对象当成了普通对象。

这个坑的触发条件是：默认值里有个Date类型的字段（比如某个时间基准点），用户配置里覆盖成字符串，合并器把Date当成了 plain object 递归进去，最后合并出一个既不是 Date 也不是字符串的怪物对象。修复就是前面isPlainObject里的原型判断——Date的原型不是Object.prototype，直接走赋值分支。教训是：合并器的类型判断宁可严格，也不要宽松，宽松判断会让你在最意想不到的地方出问题。

第四个坑：环境变量在不同 shell 里的空值语义不一致。

export WITTY_HTTP__TIMEOUT=这种写法，在有的 shell 里会设置成空字符串，在有的环境里等于未设置。空字符串经过Number('')变成0，直接把超时设成 0，请求瞬间超时。修复方法是在coerce之前先判断：if (raw === '') return undefined;，空字符串一律视为未设置。这条规则推广一下：环境变量的空字符串永远当未设置处理，因为没有人会故意把配置设成空字符串然后期望它有特殊含义。

第五个坑：doctor命令自己崩溃。

很讽刺但确实发生过。doctor要在任何情况下都能跑起来，包括配置完全错乱、缓存文件损坏、扩展全部加载失败的情况。这意味着doctor的执行路径上不能有任何“依赖配置正确性”的逻辑。实现上我把doctor做成了完全独立的命令，它自己重新走一遍加载流程，每一步都 try-catch，任何一步失败就把失败信息记进报告继续下一步。这个“诊断工具本身必须最健壮”的原则，值得单独记一笔。

实操心得：给doctor加一个--json输出选项。用户可以在 issue 里贴 JSON，你可以在本地用脚本处理。人类可读格式给自己看，JSON 格式给别人看，两个都要有。

5.3 版本升级时的配置兼容处理

配置体系一旦发布出去，就成了事实上的 API，改动成本很高。我的做法是配置对象里保留一个version字段，加载时检查版本号，跨大版本时走迁移函数。

const MIGRATIONS: Record<string, (c: Plain) => Plain> = { '1->2': (c) => ({ ...c, http: { ...(c.http as Plain), retries: 2 }, }), }; function migrate(config: Plain, targetVersion: number): Plain { let current = Number(config.version ?? 1); let result = config; while (current < targetVersion) { const key = `${current}->${current + 1}`; const fn = MIGRATIONS[key]; if (!fn) throw new WittyError(`缺少迁移路径: ${key}`, 'E_CONFIG_MIGRATE'); result = fn(result); current += 1; result.version = current; } return result; }

迁移只在内存里做，不回写用户文件——自动改用户的配置文件风险太大，万一迁移逻辑有 bug，用户的原始配置就丢了。真要回写，必须先生成一份.bak备份。doctor里可以加一条提示：“检测到旧版本配置，建议升级”，把选择权留给用户。

另一个兼容性细节是废弃配置项的处理。某个配置项不再使用时，不要直接从 schema 里删掉，否则校验会报“未知配置项”，用户一脸懵。正确做法是保留这个键，标记为deprecated，校验时只打警告不报错，警告信息里写清楚替代方案。保留期至少跨一个次版本，给用户迁移时间。

现在这个基础包已经跑了挺长一段时间，接入的项目从命令行小工具到带插件体系的复杂工具链都有。回头看，最值钱的不是那十个功能本身，而是它们之间的顺序约束和失败隔离策略——这两个东西定对了，后面加功能就是往里填，定错了，每加一个功能都在加固一个错误的结构。如果你正准备动手，我建议先把配置的层级和加载时机在纸上画一遍，把“谁依赖谁”标清楚，再开始写代码。这一步花掉的两小时，能省掉后面两周的重构。