如何用 Optique 集成配置文件:Standard Schema 校验配置完整指南,支持 Zod、Valibot 与 ArkType
如何用 Optique 集成配置文件:Standard Schema 校验配置完整指南,支持 Zod、Valibot 与 ArkType
Optique 是一个面向 TypeScript 的类型安全组合式 CLI 解析器。它的 @optique/config 包让命令行应用可以加载配置文件,并用 Standard Schema 生态(Zod、Valibot、ArkType 等)自动完成配置校验与类型推断,实现「CLI 参数 > 配置文件 > 默认值」的优先级合并。本文带你从零完成配置集成。
一、为什么 CLI 工具需要配置文件支持
CLI 工具的用户经常需要这些能力:
- 📄 持久化默认值:不想每次运行都重复输入
--host、--port等参数 - 🌍 环境区分:开发、测试、生产环境使用不同配置
- 👥 团队共享:配置文件纳入版本控制,团队使用统一设置
- ⚙️ 复杂选项:嵌套结构在命令行上难以表达
@optique/config 的核心价值:配置 schema 用任何 Standard Schema 兼容库定义,校验、类型、优先级全部自动处理。
二、安装 Optique 配置文件集成包
安装只需一步(以 npm 为例,Deno/pnpm/Yarn/Bun 同理):
npm add @optique/config @standard-schema/spec zod
💡 将
zod替换为你喜欢的验证库:valibot、arktype、yup、joi均可。配置文件 API 自 Optique 0.10.0 起提供,Standard Schema 值解析器自 1.2.0 起提供。
完整安装说明见 docs/integrations/config.md。
三、三步完成配置集成(Zod 示例)
第 1 步:定义配置 Schema 并创建 Context
用 Zod 描述你的配置文件结构,再用 createConfigContext() 创建配置上下文:
import { z } from "zod";
import { createConfigContext } from "@optique/config";
const configSchema = z.object({
host: z.string(),
port: z.number(),
});
const configContext = createConfigContext({ schema: configSchema });
第 2 步:用 bindConfig() 绑定 CLI 选项
把已有的 CLI 选项解析器「绑定」到配置文件的某个键上,并给出最终兜底默认值:
import { bindConfig } from "@optique/config";
import { option } from "@optique/core/primitives";
import { string, integer } from "@optique/core/valueparser";
const host = bindConfig(option("--host", string()), {
context: configContext,
key: "host",
default: "localhost",
});
const port = bindConfig(option("--port", integer()), {
context: configContext,
key: "port",
default: 3000,
});
第 3 步:运行时注册 Context 并指定配置文件路径
import { runAsync } from "@optique/run";
const result = await runAsync(parser, {
contexts: [configContext],
contextOptions: {
getConfigPath: (parsed) => parsed.config,
},
});
此时,~/.myapp.json 中的 {"host": "api.example.com", "port": 8080} 会自动生效;用户再执行 myapp --host localhost,则 host 取 CLI 值、port 取配置文件值。
值解析的优先级顺序
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | CLI 参数 | 用户显式传入时始终生效 |
| 2 | 配置文件值 | 经过 Schema 校验后使用 |
| 3 | 默认值 | default 兜底 |
| 4 | 报错 | 三者皆无则抛出错误 |
⚠️ 关键细节:bindConfig() 只在其 context 通过 contexts: [configContext] 注册到 runner 后才会读取配置。漏写这一行,配置查找会被静默跳过。
四、一键切换 Zod、Valibot 与 ArkType
createConfigContext() 接受任意 Standard Schema 兼容的 schema,同一套代码只需换 schema:
Zod(功能最全,~52KB)
import { z } from "zod";
const ctx = createConfigContext({
schema: z.object({ apiKey: z.string().min(32), timeout: z.number().positive() }),
});
Valibot(模块化、轻量,~10KB)
import * as v from "valibot";
const ctx = createConfigContext({
schema: v.object({ apiKey: v.pipe(v.string(), v.minLength(32)), timeout: v.pipe(v.number(), v.minValue(1)) }),
});
ArkType(字符串语法,声明式)
import { type } from "arktype";
const ctx = createConfigContext({
schema: type({ apiKey: "string>=32", timeout: "number>0" }),
});
选择建议:追求最小体积选 Valibot;需要最丰富的校验表达式选 Zod;偏好字符串类型声明选 ArkType。
五、进阶能力:嵌套配置与纯配置项
- 嵌套配置值:
key支持访问器函数,如key: (config) => config.server.host,轻松从嵌套对象取值 - 只存在于配置文件、不暴露为 CLI 参数的值:内部解析器用
fail<T>(),永远回退到配置或默认值 ~家目录展开:contextOptions中设置expandHome: true(Optique 1.4.0+),默认路径可安全写成"~/.myapp.json"- 多文件合并:通过
load回调自定义「系统 → 用户 → 项目 → 自定义」的分层加载与合并策略 - 回退值二次校验:配置文件和
default提供的值会重新经过内层 CLI 解析器约束(如integer({ min: 1024 })),无法绕过
以上能力的完整代码见 docs/integrations/config.md 与 packages/config/src/index.ts。
六、用 Standard Schema 直接校验 CLI 参数
除了配置文件,@optique/standard-schema 还能把任意 Standard Schema 校验器直接变成 CLI 参数值解析器——适合没有专用适配器的库(Yup、Joi、ArkType 等):
import { standardSchema } from "@optique/standard-schema";
import { type } from "arktype";
const email = standardSchema(type("string.email"), {
placeholder: "",
metavar: "EMAIL",
});
注意两点:
placeholder选项必填,它是一个安全的占位值,用于延迟提示解析- 校验器是异步的(返回 Promise)时,请改用
standardSchemaAsync(),并用runAsync()运行
而 Zod 和 Valibot 有专用适配器,功能更强:
| 能力 | @optique/standard-schema |
@optique/zod / @optique/valibot |
|---|---|---|
| 通用校验、类型输出 | ✅ | ✅ |
| metavar 推断、choices 补全建议 | ❌(保守策略) | ✅ |
库专属错误回调(如 zodError) |
仅通用 schemaError |
✅ |
CLI 友好布尔字面量(yes/on/1) |
❌ | ✅ |
校验失败时,Optique 会输出带上下文的友好错误信息(如上图中 --port 类型不匹配的例子),而不是生硬的堆栈。你可以用 errors.schemaError 自定义提示文案。
七、常见坑位清单
- 🔴 忘了注册 context:
run()调用中必须传contexts: [configContext],否则配置静默失效 - 🔴
placeholder缺失:创建standardSchema()时 options 必须包含placeholder,否则会抛TypeError - 🟡 同步接口遇到异步校验器:
standardSchema()遇到返回 Promise 的校验会直接抛TypeError,请切换到standardSchemaAsync() - 🟡
~不会被自动展开:Optique 不特殊处理~(它是合法文件名字符)。用expandHome: true或homedir()构建路径 - 🟢 配置文件缺失不是错误:文件不存在时安静回退到默认值,
--help、--version在配置文件损坏时依然可用
八、延伸阅读
| 资料 | 路径 |
|---|---|
| 配置文件集成完整文档 | docs/integrations/config.md |
| Standard Schema 集成文档 | docs/integrations/standard-schema.md |
| Zod 集成文档 | docs/integrations/zod.md |
| Valibot 集成文档 | docs/integrations/valibot.md |
| config 包源码 | packages/config/src/index.ts |
| standard-schema 包源码 | packages/standard-schema/src/index.ts |
| 包功能说明 | packages/config/README.md |
一句话总结:Optique 的配置文件集成让你只需一份 Standard Schema,就能同时获得类型安全的配置校验、清晰的值优先级和友好的错误提示——无论你选 Zod、Valibot 还是 ArkType。

