如何用 Optique 集成配置文件:Standard Schema 校验配置完整指南,支持 Zod、Valibot 与 ArkType

原创2026-10-29 22:52:382,210 阅读

如何用 Optique 集成配置文件:Standard Schema 校验配置完整指南,支持 Zod、Valibot 与 ArkType

Optique 是一个面向 TypeScript 的类型安全组合式 CLI 解析器。它的 @optique/config 包让命令行应用可以加载配置文件,并用 Standard Schema 生态(Zod、Valibot、ArkType 等)自动完成配置校验与类型推断,实现「CLI 参数 > 配置文件 > 默认值」的优先级合并。本文带你从零完成配置集成。

Optique 项目封面:让不可能的 CLI 状态无法表示,类型安全组合式 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",
});

注意两点:

  1. placeholder 选项必填,它是一个安全的占位值,用于延迟提示解析
  2. 校验器是异步的(返回 Promise)时,请改用 standardSchemaAsync(),并用 runAsync() 运行

而 Zod 和 Valibot 有专用适配器,功能更强:

能力 @optique/standard-schema @optique/zod / @optique/valibot
通用校验、类型输出 ✅ ✅
metavar 推断、choices 补全建议 ❌(保守策略) ✅
库专属错误回调(如 zodError) 仅通用 schemaError ✅
CLI 友好布尔字面量(yes/on/1) ❌ ✅

Optique 的 CLI 错误提示效果:配置校验失败、未知选项等场景下的友好报错与高亮示例

校验失败时,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。

登录后查看全文
optique