配置项

本页详细列出 VextJS 的所有配置字段、类型、默认值及使用说明。

配置加载机制

VextJS 使用多层配置合并策略，按优先级从低到高：

DEFAULT_CONFIG（框架内置默认值）
  ↓ 深度合并
src/config/default.ts（项目默认配置）
  ↓ 深度合并
src/config/${NODE_ENV}.ts（环境配置，如 production.ts）
  ↓ 深度合并
src/config/local.ts（本地覆盖，可选）
  ↓ provider patch
src/config/bootstrap.ts（启动期远程配置，可选）
  ↓ CLI override
vext start/dev --port --host ...

合并后的配置通过 deepFreeze() 深冻结，运行时不可修改。

配置文件清单

文件	用途	是否必须
`src/config/default.ts`	所有环境的基础配置	✅
`src/config/development.ts`	开发环境覆盖	可选
`src/config/production.ts`	生产环境覆盖	可选
`src/config/test.ts`	测试环境覆盖	可选
`src/config/local.ts`	本地覆盖（通常不提交 Git）	可选
`src/config/bootstrap.ts`	启动期 provider 注册入口	可选

`src/config/bootstrap.ts`

当数据库、密钥或配置中心 patch 需要在配置冻结前完成注入时，可新增：

import { defineBootstrapConfig } from "vextjs";

export default defineBootstrapConfig({
  providers: [
    {
      name: "remote-config",
      timeoutMs: 10_000,
      async load({ env, signal, baseConfig }) {
        const response = await fetch(`https://config.example.com/${env}.json`, {
          signal,
        });
        const remote = await response.json();
        return {
          database: remote.database,
          logger: {
            lifecycleLevel: baseConfig.logger?.lifecycleLevel ?? "concise",
          },
        };
      },
    },
  ],
});

约束：

provider 必须返回 plain object patch 或 null
patch 只支持 JSON-like 结构
required 未声明时：production 默认 fail-fast，development / test 默认 warning 后继续
Cluster 模式下，同一启动周期会复用同一份 provider patch，避免 Master / Worker 看到不同结果

配置文件示例

// src/config/default.ts
export default {
  port: 3000,
  adapter: "native",
  cors: {
    enabled: true,
    origins: ["http://localhost:3000"],
  },
  logger: {
    level: "debug",
  },
};

// src/config/production.ts
export default {
  port: 8080,
  cors: {
    origins: ["https://api.example.com"],
  },
  logger: {
    level: "warn",
  },
  response: {
    hideInternalErrors: true,
  },
};

完整配置参考

`VextConfig`

字段	类型	默认值	说明
`port`	`number`	`3000`	HTTP 监听端口
`host`	`string`	`'0.0.0.0'`	HTTP 监听地址
`adapter`	`string \| Function \| VextAdapter`	`'native'`	底层适配器
`trustProxy`	`boolean`	`false`	是否信任代理
`middlewares`	`VextMiddlewareConfig[]`	`[]`	路由级中间件白名单
`cors`	`VextCorsConfig`	见下方	CORS 配置
`rateLimit`	`VextRateLimitConfig`	见下方	速率限制配置
`requestId`	`VextRequestIdConfig`	见下方	请求 ID 配置
`logger`	`VextLoggerConfig`	见下方	日志配置
`shutdown`	`VextShutdownConfig`	见下方	优雅关闭配置
`server`	`VextServerConfig`	`{}`	Node.js HTTP server 配置
`response`	`VextResponseConfig`	见下方	响应配置
`bodyParser`	`VextBodyParserConfig`	见下方	Body 解析配置
`multipart`	`VextMultipartConfig`	`undefined`	文件上传配置
`accessLog`	`VextAccessLogConfig`	见下方	访问日志配置
`openapi`	`VextOpenAPIConfig`	见下方	OpenAPI 文档配置
`requestContext`	`VextRequestContextConfig`	见下方	请求上下文配置
`fetch`	`VextFetchConfig`	见下方	内置 HTTP 客户端与代理配置
`cluster`	`Partial<VextClusterConfig>`	`undefined`	Cluster 多进程配置

`adapter`

底层 HTTP 适配器，支持三种传参方式：

// 方式一：字符串标识（内置 adapter）
export default {
  adapter: "native", // 'native' | 'hono' | 'fastify' | 'express' | 'koa'
};

// 方式二：工厂函数（传入自定义选项）
import { fastifyAdapter } from "vextjs/adapters/fastify";

export default {
  adapter: fastifyAdapter({ bodyLimit: 5 * 1024 * 1024 }),
};

// 方式三：自定义 adapter 实例（实现 VextAdapter 接口）
export default {
  adapter: myCustomAdapter,
};

`trustProxy`

当设置为 true 时：

req.ip 从 X-Forwarded-For 请求头读取第一个 IP
req.protocol 从 X-Forwarded-Proto 请求头读取

部署在 Nginx / 云负载均衡器之后时需开启此选项。

`middlewares`

路由级中间件白名单声明。只有在此处声明的中间件才能在路由 options.middlewares 中引用。

export default {
  middlewares: [
    { name: "auth" },
    { name: "admin", options: { role: "admin" } },
    { name: "client-cache", options: { maxAge: 60 } },
  ],
};

Tip

全局中间件（如 CORS、body-parser）由框架自动注册，无需在此声明。此处只声明路由级可选中间件。

VextCorsConfig

跨域资源共享配置。

字段	类型	默认值	说明
`enabled`	`boolean`	`true`	是否启用 CORS
`origins`	`string[]`	`['*']`	允许的来源域名
`methods`	`string[]`	`['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']`	允许的 HTTP 方法
`headers`	`string[]`	`['Content-Type', 'Authorization', 'X-Request-Id']`	允许的请求头
`credentials`	`boolean`	`false`	是否允许携带凭证
`maxAge`	`number`	`undefined`	CORS 预检结果缓存时间（秒）

export default {
  cors: {
    enabled: true,
    origins: ["https://app.example.com", "https://admin.example.com"],
    credentials: true,
    maxAge: 86400,
  },
};

Warning

origins: ['*'] 与 credentials: true 不能同时使用。需要携带凭证时必须指定具体域名。

VextRateLimitConfig

全局速率限制配置，基于 flex-rate-limit 实现。

字段	类型	默认值	说明
`enabled`	`boolean`	`true`	是否启用速率限制
`max`	`number`	`100`	时间窗口内最大请求数
`window`	`number`	`60`	时间窗口（秒）
`message`	`string`	`'Too Many Requests'`	超限错误消息
`keyBy`	`string \| Function`	`'ip'`	请求来源标识

export default {
  rateLimit: {
    max: 200,
    window: 120,
    // 按用户 ID 限流（需要 auth 中间件先解析用户）
    keyBy: (req) => req.user?.id ?? req.ip,
  },
};

`keyBy` 选项

值	说明
`'ip'`	按客户端 IP 限流（默认）
`'user'`	按 `req.user?.id` 限流
`(req) => string`	自定义函数，返回唯一标识

Tip

路由级可通过 options.override.rateLimit 覆盖全局配置，或设为 false 禁用限流。

VextRequestIdConfig

请求 ID 追踪配置，用于日志关联和分布式链路追踪。

字段	类型	默认值	说明
`enabled`	`boolean`	`true`	是否启用请求 ID
`header`	`string`	`'x-request-id'`	从哪个请求头读取（网关透传）
`responseHeader`	`string`	`'x-request-id'`	写入响应头的名称
`generate`	`() => string`	`crypto.randomUUID()`	自定义 ID 生成函数

requestId vs traceId

requestId 是 vext 内置的请求唯一标识，traceId 通常指 APM 链路追踪系统（如 OpenTelemetry / Jaeger）生成的追踪 ID。两者有不同的使用场景：

模式一：requestId 充当 traceId（简单场景）

将 requestId 的请求头名改为 x-trace-id，使其与链路追踪头统一，适合不依赖外部 APM 的系统：

import { nanoid } from "nanoid";

export default {
  requestId: {
    header: "x-trace-id", // 从 x-trace-id 读取（网关注入）
    responseHeader: "x-trace-id", // 写回响应头
    generate: () => nanoid(), // 可替换为更短的 ID 生成器
  },
};

模式二：requestId + APM traceId 并存（企业级场景）

保留 requestId（日志关联），同时通过 config.fetch.propagateHeaders 透传 APM 的 traceparent 头，适合接入 OpenTelemetry / Jaeger 等系统：

export default {
  // requestId 保留默认配置（用于日志关联）
  requestId: {
    header: "x-request-id",
    responseHeader: "x-request-id",
  },
  // APM 追踪头通过 propagateHeaders 自动透传到下游服务
  fetch: {
    propagateHeaders: ["traceparent", "tracestate"],
  },
};

选择建议

内部系统、简单追踪 → 模式一（改 header 名为 x-trace-id）
接入 OpenTelemetry / Jaeger / Datadog → 模式二（保留 requestId，配置 propagateHeaders）
详见请求上下文 → 与分布式追踪的关系 :::

也可通过插件动态替换生成器：

app.setRequestIdGenerator(() => myCustomId());

VextFetchConfig

内置 HTTP 客户端与请求代理配置。

字段	类型	默认值	说明
`timeout`	`number`	`10000`	`app.fetch` 与 `app.fetch.proxy` 默认超时
`retry`	`number`	`0`	默认重试次数，表示额外尝试次数
`retryDelay`	`number \| (attempt: number) => number`	`1000`	默认重试间隔，支持函数形式
`propagateHeaders`	`string[]`	`[]`	普通 `app.fetch` 自动透传的请求头白名单
`proxy`	`VextFetchProxyTargetConfig[]`	`[]`	`app.fetch.proxy.<name>()` 的上游目标列表

export default {
  fetch: {
    timeout: 10_000,
    retry: 1,
    retryDelay: 500,
    propagateHeaders: ["traceparent", "x-tenant-id"],
    proxy: [
      {
        name: "userService",
        baseURL: "http://user-service:3001/api",
        forwardHeaders: ["x-tenant-id"],
        headers: { "x-source": "gateway" },
        timeout: 5000,
        retry: 1,
      },
    ],
  },
};

VextFetchProxyTargetConfig

字段	类型	必填	说明
`name`	`string`	✅	目标名称，对应 `app.fetch.proxy.<name>()`；不能使用保留名 `then`
`baseURL`	`string`	✅	上游基础 URL
`headers`	`Record<string, string>`	❌	目标级固定请求头
`forwardHeaders`	`string[]`	❌	从当前 `req.headers` 透传的请求头白名单
`defaultInjectHeaders`	`Record<string, string> \| Function`	❌	目标级动态注入 headers
`allowAuthorizationForward`	`boolean`	❌	是否允许透传原始 Authorization
`timeout`	`number`	❌	目标级超时
`retry`	`number`	❌	目标级重试次数
`retryDelay`	`number \| (attempt: number) => number`	❌	目标级重试间隔

代理请求头优先级：target.headers < forwardHeaders < target.defaultInjectHeaders < options.headers < options.injectHeaders。Authorization 默认不透传，必须同时配置白名单和 allowAuthorizationForward: true。

代理 retry 优先级：options.retry > target.retry > config.fetch.retry > 0。仅 GET / HEAD / OPTIONS / PUT / DELETE 会在上游 5xx 或网络错误时自动重试；POST / PATCH 默认不重试，超时不重试并返回本地 504。

VextLoggerConfig

结构化日志配置，基于 Vext 内置 logger kernel 实现。

字段	类型	默认值	说明
`level`	`'fatal' \| 'error' \| 'warn' \| 'info' \| 'debug' \| 'trace' \| 'silent'`	`'info'`	日志级别
`lifecycleLevel`	`'concise' \| 'verbose'`	`'concise'`	框架生命周期日志详细程度，控制启动、loader、hot reload、cluster 等系统日志输出
`pretty`	`boolean`	开发环境 `true`	是否使用内置 pretty formatter 输出可读格式
`prettyIgnore`	`string`	`'pid,hostname,requestId'`	pretty 模式下忽略的字段（逗号分隔）。默认隐藏 `requestId` 避免 mixin 注入的字段被展开为多行噪音，生产环境 JSON 输出不受影响
`prettySingleLine`	`boolean`	`true`	pretty 模式下是否将额外字段以 JSON 内联形式压缩到消息同一行。设为 `false` 使用多行展开格式。仅影响 pretty 模式，生产环境 JSON 输出不受影响
`redactKeys`	`string[]`	`[]`	按任意层级 exact key 脱敏结构化日志字段。顶层 `level` 为日志协议字段，不会被改写
`redactPaths`	`string[]`	`[]`	按 dot notation exact path 脱敏结构化日志字段，支持数组数字下标；不支持 wildcard、bracket notation、remove 或 function censor
`redactValue`	`string`	`'[Redacted]'`	脱敏替换值
`mixin`	`() => Record<string, unknown>`	`undefined`	自定义日志 mixin 函数，返回值会与框架内置字段合并注入每条日志。`requestId` 是框架保护字段，不可被用户 mixin 覆盖；`trace_id` / `span_id` 等其他字段按用户 mixin 优先。典型用途：注入 OpenTelemetry `trace_id` / `span_id`，实现日志与链路追踪关联。未配置时不会执行用户 mixin 调用。

export default {
  logger: {
    level: "debug",
    pretty: true, // 开发环境美化输出
    // prettySingleLine: true,                   // 默认值，额外字段压缩到消息同一行
    // prettySingleLine: false,                  // 恢复多行展开格式
    // prettyIgnore: 'pid,hostname,requestId',   // 默认值，隐藏 requestId
    // prettyIgnore: 'pid,hostname',             // 如需在 pretty 模式下显示 requestId
    // redactKeys: ['password', 'token'],
    // redactPaths: ['user.email', 'headers.authorization'],
    // redactValue: '[Redacted]',
  },
};

日志级别优先级（从高到低）：

fatal > error > warn > info > debug > trace

设置某个级别后，只输出该级别及更高级别的日志。设为 'silent' 完全静默。

默认 logger 还支持运行时 app.logger.getLevel() / app.logger.setLevel(level) 调整后续日志阈值；配置对象本身仍会在启动后冻结，不应通过修改 app.config.logger.level 动态变更。

VextShutdownConfig

优雅关闭配置。

字段	类型	默认值	说明
`timeout`	`number`	`10`	关闭超时（秒）

收到 SIGTERM / SIGINT 信号后，框架会：

停止接受新请求
等待飞行中请求完成（不超过 timeout 秒）
按 LIFO 顺序执行所有 onClose 钩子
退出进程

export default {
  shutdown: {
    timeout: 30, // 容器环境建议 30 秒
  },
};

VextServerConfig

入站 Node.js HTTP server 层配置。适用于内置 Native / Hono / Fastify / Express / Koa adapter，也适用于 vext dev 创建的开发 server。未设置字段保持当前 Node.js 默认值。

字段	类型	默认值	说明
`requestTimeout`	`number`	Node.js 默认值	接收完整请求的最大时间（毫秒），`0` 表示禁用
`headersTimeout`	`number`	Node.js 默认值	接收完整 HTTP headers 的最大时间（毫秒）
`keepAliveTimeout`	`number`	Node.js 默认值	响应完成后 keep-alive 空闲等待时间（毫秒）
`socketTimeout`	`number`	Node.js 默认值	socket inactivity timeout（毫秒），`0` 表示禁用
`maxHeaderSize`	`number`	Node.js 默认值	最大请求头大小（bytes）
`maxRequestsPerSocket`	`number`	Node.js 默认值	单 socket 最大请求数，`0` 表示不限
`connectionsCheckingInterval`	`number`	Node.js 默认值	未完成请求超时检查间隔（毫秒）

export default {
  server: {
    requestTimeout: 120_000,
    headersTimeout: 60_000,
    keepAliveTimeout: 5_000,
    socketTimeout: 0,
    maxHeaderSize: 16 * 1024,
    maxRequestsPerSocket: 0,
    connectionsCheckingInterval: 30_000,
  },
};

config.server 只控制入站服务请求。出站 app.fetch / app.fetch.proxy 的超时由 config.fetch.timeout、代理目标 timeout 或调用时 options 控制。

VextResponseConfig

响应格式配置。

字段	类型	默认值	说明
`hideInternalErrors`	`boolean`	`true`	是否隐藏 500 错误详情
`wrap`	`boolean`	`true`	是否启用出口包装

出口包装

启用 wrap: true 时，res.json(data) 自动包装：

{
  "code": 0,
  "data": { "id": 1, "name": "Alice" },
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

错误响应格式：

{
  "code": 10001,
  "message": "用户不存在",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

禁用 wrap: false 时，res.json(data) 直接发送原始 data。

隐藏内部错误

hideInternalErrors 只影响“未知异常”这条 500 错误路径，例如路由、service、middleware 中直接 throw new Error("...") 的场景。它不会改变 app.throw(...) 或 VextValidationError 这类结构化错误的状态码与响应格式。

hideInternalErrors: true 时，500 错误不暴露 stack trace：

// hideInternalErrors: true
{ "code": 500, "message": "Internal Server Error" }

// hideInternalErrors: false（仅开发环境使用）
{ "code": 500, "message": "Internal Server Error", "stack": "..." }

VextBodyParserConfig

请求体解析配置。

字段	类型	默认值	说明
`enabled`	`boolean`	`true`	是否启用 body 解析
`maxBodySize`	`string \| number`	`'1mb'`	最大请求体大小

export default {
  bodyParser: {
    maxBodySize: "5mb", // 支持 'kb', 'mb', 'gb' 单位
  },
};

禁用后 req.body 始终为 undefined，适用于纯 GET 服务或自定义 body 解析场景。

maxBodySize 支持的格式：

格式	示例	说明
字符串	`'1mb'`, `'512kb'`, `'10mb'`	支持 kb/mb/gb 单位
数字	`1048576`	直接指定字节数

VextMultipartConfig

Multipart / 文件上传全局配置。

字段	类型	默认值	说明
`enabled`	`boolean`	`false`	是否启用内置 multipart 解析。设为 `true` 后 body-parser 自动填充 `req.files`，无需插件
`maxFileSize`	`number`	`10485760`	单个文件最大大小（字节，默认 10MB）
`maxFiles`	`number`	`10`	单次请求最多文件数
`allowedMimeTypes`	`string[]`	`undefined`	允许的 MIME 类型白名单（不设置则不限制）

export default {
  multipart: {
    enabled: true, // 开启内置解析
    maxFileSize: 10 * 1024 * 1024, // 10MB
    maxFiles: 5,
    allowedMimeTypes: [
      "image/jpeg",
      "image/png",
      "image/gif",
      "application/pdf",
    ],
  },
};

:::tip Fastify 联动 multipart.maxFileSize 只限制单个文件大小；总请求体读取上限由 bodyParser.maxBodySize 控制。使用 Fastify 时，如额外传入 fastifyAdapter({ bodyLimit })，实际读取边界会取 adapter bodyLimit 与 body-parser 总体上限中的较小值。

VextAccessLogConfig

访问日志配置，基于洋葱模型 after-middleware 实现。

字段	类型	默认值	说明
`enabled`	`boolean`	`true`	是否启用访问日志
`level`	`string`	`'info'`	基础日志级别，仅支持 `'info'` 或 `'debug'`
`skipPaths`	`string[]`	`[]`	精确匹配跳过的路径列表
`skipPathPrefixes`	`string[]`	`[]`	前缀匹配跳过的路径列表
`slowThreshold`	`number`	`0`	慢请求阈值，`0` 表示不启用
`warnOn4xx`	`boolean`	`false`	是否将 4xx 响应提升为 `warn`
`logResponseSize`	`boolean`	`false`	是否在消息末尾追加响应体大小

export default {
  accessLog: {
    enabled: true,
    level: "info",
    skipPaths: ["/health", "/readiness", "/metrics"],
    skipPathPrefixes: ["/internal"],
    slowThreshold: 1000,
    warnOn4xx: false,
    logResponseSize: false,
  },
};

访问日志输出示例：

POST /api/users 201 12ms | 192.168.1.1

消息字段包括 HTTP 方法、路径、状态码、响应时间（ms）和客户端 IP；requestId 由 logger 的 AsyncLocalStorage mixin 自动注入到 JSON 记录字段。

VextOpenAPIConfig

OpenAPI 文档自动生成配置。

字段	类型	默认值	说明
`enabled`	`boolean`	dev 启用，prod 关闭	是否启用
`title`	`string`	`undefined`	文档标题
`version`	`string`	`undefined`	文档版本号
`description`	`string`	`undefined`	文档描述
`docsPath`	`string`	`'/docs'`	Scalar 文档路径
`jsonPath`	`string`	`'/openapi.json'`	OpenAPI JSON 路径
`jsonPublicPath`	`string`	同 `jsonPath`	OpenAPI spec 的公开访问路径（仅影响 Scalar HTML 中引用 spec 的 URL，不影响路由注册）。用于反向代理剥离前缀场景，详见指南
`contact`	`object`	`undefined`	联系信息
`license`	`object`	`undefined`	许可证信息
`servers`	`array`	`undefined`	服务器地址列表
`tags`	`array`	`undefined`	全局标签定义
`guardSecurityMap`	`Record<string, string>`	`undefined`	Guard → Security Scheme 映射
`securitySchemes`	`object`	`undefined`	安全方案定义
`scalar`	`object`	`{}`	Scalar API Reference UI 配置（主题、深色模式、布局、favicon 等）
`scalar.theme`	`string`	`'default'`	主题：`'default'` \| `'moon'` \| `'purple'` \| `'solarized'` \| `'bluePlanet'` \| `'saturn'` \| `'kepler'` \| `'mars'` \| `'deepSpace'` \| `'none'`
`scalar.darkMode`	`boolean`	`false`	是否启用深色模式
`scalar.layout`	`string`	`'modern'`	布局模式：`'modern'`（三栏） \| `'classic'`（双栏）
`scalar.favicon`	`string`	`undefined`	文档页面 favicon URL（如 `'/favicon.svg'`）
`scalar.sources`	`array`	`undefined`	多 OpenAPI 文档源（详见指南）。每项含 `title`、`url` 或 `content`、`slug`
`scalar.cdnUrl`	`string`	jsDelivr CDN	自定义 Scalar JS 加载地址（详见指南）。适用于内网/离线/版本锁定
`scalar.showSidebar`	`boolean`	`true`	是否显示侧边栏
`scalar.hideModels`	`boolean`	`false`	是否隐藏 Models/Schemas 面板
`scalar.hiddenClients`	`string[]`	`undefined`	隐藏的客户端语言列表（如 `['php', 'ruby']`）
`scalar.searchHotKey`	`string`	`'k'`	搜索热键（Ctrl+K / Cmd+K）
`scalar.proxyUrl`	`string`	`undefined`	代理 URL（Try it out 请求避免 CORS）
`scalar.customCss`	`string`	`undefined`	自定义 CSS
~~`tryItOutEnabled`~~	`boolean`	`true`	~~已废弃~~ Scalar 内置 Try it out，无需单独配置
~~`docExpansion`~~	`'none' \| 'list' \| 'full'`	`'list'`	~~已废弃~~ 请使用 `scalar.layout` 替代

export default {
  openapi: {
    enabled: true,
    title: "My API",
    version: "1.0.0",
    description: "我的 API 文档",
    scalar: {
      theme: "default",
      darkMode: false,
      layout: "modern",
      favicon: "/favicon.svg",
    },
    servers: [
      { url: "http://localhost:3000", description: "开发环境" },
      { url: "https://api.example.com", description: "生产环境" },
    ],
    tags: [
      { name: "用户", description: "用户管理接口" },
      { name: "订单", description: "订单管理接口" },
    ],
    securitySchemes: {
      bearerAuth: {
        type: "http",
        scheme: "bearer",
        bearerFormat: "JWT",
      },
    },
    guardSecurityMap: {
      auth: "bearerAuth",
    },
  },
};

`guardSecurityMap`

将路由中间件名称自动映射为 OpenAPI Security Scheme：

// 路由声明中使用 auth 中间件
app.get("/profile", { middlewares: ["auth"] }, handler);
// ↑ OpenAPI 自动推断该路由需要 bearerAuth 认证

`securitySchemes`

支持的安全方案类型：

`type`	说明	必填字段
`http`	HTTP 认证	`scheme`（`bearer` / `basic`）
`apiKey`	API Key	`name`, `in`（`header` / `query` / `cookie`）
`oauth2`	OAuth 2.0	—
`openIdConnect`	OpenID Connect	—

VextRequestContextConfig

AsyncLocalStorage 请求上下文配置。

字段	类型	默认值	说明
`enabled`	`boolean`	`true`	是否启用请求上下文

export default {
  requestContext: {
    enabled: false, // 禁用后可提升 3-8% RPS
  },
};

:::warning 禁用后以下功能失效：

Logger 自动注入 requestId
app.throw() 自动解析请求级 locale
app.fetch() 自动传播 requestId :::

VextClusterConfig

Cluster 多进程配置。完整接口定义见 src/types/app.ts VextClusterConfig。

基础字段

字段	类型	默认值	说明
`enabled`	`boolean`	`false`	是否启用 Cluster 模式（也可通过 `VEXT_CLUSTER=1` 开启）
`workers`	`'auto' \| 'auto-1' \| number`	`'auto'`	Worker 数量（`'auto'` = CPU 核心数；`'auto-1'` = CPU 核心数 - 1；number = 固定数量，clamp 到 [1, 64]）
`autoRestart`	`boolean`	`true`	Worker 崩溃后自动重启
`maxRestarts`	`number`	`5`	快速重启检测窗口内允许的最大重启次数
`restartWindow`	`number`	`60000`	快速重启检测窗口（毫秒）
`restartBaseDelay`	`number`	`1000`	重启间隔退避基数（毫秒）
`restartMaxDelay`	`number`	`30000`	重启间隔上限（毫秒）
`pidFile`	`string`	`'.vext.pid'`	PID 文件路径（供 `vext stop` / `vext reload` 定位进程）
`titlePrefix`	`string`	`'vext'`	Worker 进程标题前缀
`sticky`	`'none' \| 'ip'`	`'none'`	粘性会话模式（`'ip'` 基于客户端 IP 分配固定 Worker，适用于 WebSocket / SSE）

`healthCheck` — 心跳检测

字段	类型	默认值	说明
`healthCheck.enabled`	`boolean`	`true`	是否启用 Worker 心跳检测
`healthCheck.interval`	`number`	`15000`	Master 发送心跳探测的间隔（毫秒）
`healthCheck.timeout`	`number`	`30000`	Worker 心跳超时阈值（毫秒），超时则强制重启

`reload` — 零停机滚动重启

字段	类型	默认值	说明
`reload.workerDelay`	`number`	`2000`	替换下一个 Worker 前的等待时间（毫秒）
`reload.readyTimeout`	`number`	`30000`	新 Worker 就绪超时（毫秒）
`reload.shutdownTimeout`	`number`	`10000`	旧 Worker 关闭超时（毫秒）

export default {
  cluster: {
    enabled: true,
    workers: "auto", // 充分利用所有 CPU 核心
    autoRestart: true,
    maxRestarts: 5,
    healthCheck: {
      enabled: true,
      interval: 15000,
      timeout: 30000,
    },
    reload: {
      workerDelay: 2000,
      readyTimeout: 30000,
      shutdownTimeout: 10000,
    },
  },
};

也可通过环境变量启用（无需修改配置文件）：

VEXT_CLUSTER=1 vext start

VextCacheConfig

路由级响应缓存全局配置。

字段	类型	默认值	说明
`enabled`	`boolean`	`true`	是否启用路由级响应缓存。设为 `false` 后不安装缓存中间件，也不会打开 Redis/MultiLevel 连接
`defaultTtl`	`number`	`60000`	路由未指定 TTL 时的默认值，单位毫秒
`maxEntries`	`number`	`1000`	Memory 模式快捷配置：最大缓存条目数
`maxMemory`	`number`	—	Memory 模式快捷配置：最大内存占用 bytes
`cleanupInterval`	`number`	`0`	Memory 模式快捷配置：周期清理间隔，`0` 表示只做惰性清理
`cacheHub`	`object`	Memory	底层响应缓存运行时配置

export default {
  cache: {
    enabled: true,
    defaultTtl: 120_000,
    maxEntries: 2000,
  },
};

Memory 完整配置：

export default {
  cache: {
    defaultTtl: 60_000,
    cacheHub: {
      mode: "memory",
      maxEntries: 1000,
      maxMemory: 50 * 1024 * 1024,
      cleanupInterval: 30_000,
      enableStats: true,
    },
  },
};

Redis 配置：

export default {
  cache: {
    defaultTtl: 2_000,
    cacheHub: {
      mode: "redis",
      url: "redis://localhost:6379",
      deleteCommand: "unlink",
      lease: {
        waitForOwner: 1_000,
        onTimeout: "fetch",
      },
      distributed: {
        channel: "vext:response-cache",
      },
    },
  },
};

MultiLevel 配置：

export default {
  cache: {
    defaultTtl: 60_000,
    cacheHub: {
      mode: "multi-level",
      memory: { maxEntries: 1000 },
      redis: { url: "redis://localhost:6379" },
      writePolicy: "both",
      backfillOnRemoteHit: true,
      remoteTimeout: 50,
      lease: true,
    },
  },
};

cacheHub 只接受 response-cache-kit/cache-hub 配置，不接受自定义 Store。路由级响应缓存通过 RouteOptions.cache 配置。公开配置单位使用毫秒；响应头中的 Cache-Control: max-age 会按 HTTP 标准输出秒。详见响应缓存指南。

DEFAULT_CONFIG

框架内置默认配置的完整值：

import { DEFAULT_CONFIG } from 'vextjs';

// DEFAULT_CONFIG 的完整内容：
{
  port: 3000,
  host: '0.0.0.0',
  adapter: 'native',
  trustProxy: false,
  middlewares: [],
  cors: {
    enabled: true,
    origins: ['*'],
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
    headers: ['Content-Type', 'Authorization', 'X-Request-Id'],
    credentials: false,
  },
  rateLimit: {
    enabled: true,
    max: 100,
    window: 60,
    message: 'Too Many Requests',
    keyBy: 'ip',
  },
  requestId: {
    enabled: true,
    header: 'x-request-id',
    responseHeader: 'x-request-id',
  },
  logger: {
    level: 'info',
  },
  shutdown: {
    timeout: 10,
  },
  response: {
    hideInternalErrors: true,
    wrap: true,
  },
  bodyParser: {
    enabled: true,
    maxBodySize: '1mb',
  },
  accessLog: {
    enabled: true,
    level: 'info',
    skipPaths: [],
  },
  openapi: {
    enabled: false,
  },
  requestContext: {
    enabled: true,
  },
}

VextUserConfig

用户配置的输入类型，所有字段均为可选。由 loadConfig() 合并默认值后生成完整的 VextConfig。

import type { VextUserConfig } from "vextjs";

const config: VextUserConfig = {
  port: 8080,
  logger: { level: "debug" },
};

export default config;

loadConfig

配置加载函数，接收配置目录路径并执行完整配置链合并。

import { loadConfig } from "vextjs";
import { join } from "node:path";

const config = await loadConfig(join(process.cwd(), "src/config"), {
  rootDir: process.cwd(),
  command: "start",
  isBuilt: false,
});
// config: VextConfig（已合并、已冻结）

通常不需要手动调用，bootstrap() 内部会自动调用 loadConfig()。合并顺序为：DEFAULT_CONFIG < default < env < local < bootstrap provider patch < CLI override。

环境变量覆盖

部分配置支持通过环境变量覆盖：

环境变量	对应配置	说明
`PORT`	`port`	HTTP 监听端口
`HOST`	`host`	HTTP 监听地址
`NODE_ENV`	—	决定加载哪个环境配置文件
`VEXT_CLUSTER`	`cluster.enabled`	设为 `1` 启用集群

PORT=8080 NODE_ENV=production vext start

类型声明扩展

插件可通过 declare module 为 VextConfig 添加自定义字段：

// types/vext.d.ts
declare module "vextjs" {
  interface VextConfig {
    redis?: {
      host: string;
      port: number;
      password?: string;
    };
  }
}

之后在配置文件中使用将获得完整的类型提示：

// src/config/default.ts
export default {
  redis: {
    host: "localhost",
    port: 6379,
  },
};

#配置项

#配置加载机制

#配置文件清单

#src/config/bootstrap.ts

#配置文件示例

#完整配置参考

#VextConfig

#adapter

#trustProxy

#middlewares

#VextCorsConfig

#VextRateLimitConfig

#keyBy 选项

#VextRequestIdConfig

#requestId vs traceId

#VextFetchConfig

#VextFetchProxyTargetConfig

#VextLoggerConfig

#VextShutdownConfig

#VextServerConfig

#VextResponseConfig

#出口包装

#隐藏内部错误

#VextBodyParserConfig

#VextMultipartConfig

#VextAccessLogConfig

#VextOpenAPIConfig

#guardSecurityMap

#securitySchemes

#VextRequestContextConfig

#VextClusterConfig

#基础字段

#healthCheck — 心跳检测

#reload — 零停机滚动重启

#VextCacheConfig

#DEFAULT_CONFIG

#VextUserConfig

#loadConfig

#环境变量覆盖

#类型声明扩展

配置项