配置项
本页详细列出 VextJS 的所有配置字段、类型、默认值及使用说明。
配置加载机制
VextJS 使用多层配置合并策略，按优先级从低到高：
DEFAULT_CONFIG（框架内置默认值）
↓ 深度合并
src/config/default.ts（项目默认配置）
↓ 深度合并
src/config/{profile}.ts（配置 profile，如 production.ts 或 sg-sit.ts）
↓ 深度合并
src/config/local.ts（本地覆盖，可选）
↓ provider patch
src/config/bootstrap.ts（启动期远程配置，可选）
↓ CLI override
vext start/dev --port --host ...
合并后的配置通过 deepFreeze() 深冻结，运行时不可修改。
配置文件清单
src/config/bootstrap.ts
当数据库、密钥或配置中心 patch 需要在配置冻结前完成注入时，可新增：
import { defineBootstrapConfig } from "vextjs";
export default defineBootstrapConfig({
providers: [
{
name: "remote-config",
timeoutMs: 10_000,
async load({ configProfile, signal, baseConfig }) {
const response = await fetch(
`https://config.example.com/${configProfile}.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
host 支持 "0.0.0.0"、"::"、具体 IPv4、具体 IPv6 和主机名。配置为 "::" 时，ready 日志会同时展示 IPv4 local URL 与 bracketed IPv6 local/network URL（例如 http://[::1]:3000）；具体 IPv6 host 也会以方括号 URL 格式输出。
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 请求头读取第一个 IPreq.protocol 从 X-Forwarded-Proto 请求头读取
部署在 Nginx / 云负载均衡器之后时需开启此选项。
middlewares
路由级中间件白名单声明。只有在此处声明的中间件才能在路由 options.middlewares 中引用。
export default {
middlewares: [
{ name: "auth" },
{ name: "framework-auth" },
{ name: "admin", options: { role: "admin" } },
{ name: "client-cache", options: { maxAge: 60 } },
],
};
Tip
全局中间件（如 CORS、body-parser）由框架自动注册，无需在此声明。此处只声明路由级可选中间件。
Vext 内置 auth() helper 仍然以路由级中间件文件注册，路由再通过 RouteOptions.auth 选择是否保护：
// src/middlewares/framework-auth.ts
import { auth, defineMiddleware } from "vextjs";
export default defineMiddleware(
auth({
async verify(token) {
return token === "demo-token" ? { userId: "1" } : false;
},
}),
);
VextCorsConfig
跨域资源共享配置。
export default {
cors: {
enabled: true,
origins: ["https://app.example.com", "https://admin.example.com"],
credentials: true,
maxAge: 86400,
},
};
Warning
origins: ['*'] 与 credentials: true 不能同时使用。需要携带凭证时必须指定具体域名。
全局速率限制配置，基于 flex-rate-limit 实现。
export default {
rateLimit: {
max: 200,
window: 120,
// 按用户 ID 限流（需要 auth 中间件先解析用户）
keyBy: (req) => req.user?.id ?? req.ip,
},
};
keyBy 选项
Tip
路由级可通过 options.override.rateLimit 覆盖全局配置，或设为 false 禁用限流。
VextRequestIdConfig
请求 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 必须是大于 0 且不超过 2147483647 毫秒的有限数字；retryDelay 必须是 0 或正数且不超过 2147483647 毫秒，函数形式的返回值也会在运行时校验。
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
代理请求头优先级：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 实现。
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
优雅关闭配置。
收到 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 默认值。
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
响应格式配置。
出口包装
启用 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
请求体解析配置。
export default {
bodyParser: {
maxBodySize: "5mb", // 支持 'kb', 'mb', 'gb' 单位
},
};
禁用后 req.body 始终为 undefined，适用于纯 GET 服务或自定义 body 解析场景。
maxBodySize 支持的格式：
VextMultipartConfig
Multipart / 文件上传全局配置。
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 实现。
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 文档自动生成配置。
docs.access.cacheKey 不是当前版本支持的配置字段。Vext 会拒绝该字段，避免让用户误以为文档访问链路已经提供 response cache 或 access result cache。
固定本地或部署 API 目标时，servers[].url 建议直接写带端口的完整 base URL，例如 http://127.0.0.1:3000。只有环境名、区域、租户或 API 版本这类真正会变化的 URL 片段，才建议使用 servers[].variables。docs.tryItOut.defaultServer 用于控制 Try it out 初始选中的 server，docs.tryItOut.customServer 用于允许用户在浏览器里临时输入其他目标地址，不需要修改项目配置。
tagGroups 只有在显式配置时才会透传为 x-tagGroups。默认 Vext Docs renderer 使用 OpenAPI path segment 构建递归导航；tagGroups 主要用于下游 OpenAPI 工具明确消费该 vendor extension 的场景。
默认 Vext Docs renderer 会从 code docs 数据生成 Services / Utils / Models / Components / Plugins / Middlewares。Model 条目可展示静态 schema fields、enums、options、indexes、methods、hooks 和 usage；Plugins 与 Middlewares 可展示可推断的 lifecycle/bootstrap、app extension、middleware 类型、route usage 和源码链接；Locales / Config / Styles / Preload 属于可选高级静态来源，可在 docs.code 下显式开启，但不进入默认顶层文档入口；本地 loopback 文档页还可为 code docs 条目展示 Open source 链接，不需要新增单独配置项。
export default {
openapi: {
enabled: true,
title: "My API",
version: "1.0.0",
description: "我的 API 文档",
docs: {
path: "/docs",
renderer: "vext",
code: {
enabled: "auto",
},
},
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 历史回退
用于把只声明 middleware 的历史路由映射到 OpenAPI Security Scheme。新的 Auth 示例应优先通过本地 route guard helper 使用 RouteOptions.auth，让运行时保护和 OpenAPI security 共用同一个真相源：
// 仅用于历史兼容：没有 RouteOptions.auth 的 middleware 名称推断
app.get("/profile", { middlewares: ["auth"] }, handler);
// ↑ OpenAPI 自动推断该路由需要 bearerAuth 认证
securitySchemes
支持的安全方案类型：
对于 in: "cookie" 的 apiKey 安全方案和 validate.cookie 参数，内置文档可以展示字段，但浏览器 Try it out 不能直接设置受限的 Cookie header。如需手动 cookie 值，请使用同源浏览器 cookie 或 HTTP 客户端。
VextRequestContextConfig
AsyncLocalStorage 请求上下文配置。
export default {
requestContext: {
enabled: false, // 禁用后可提升 3-8% RPS
},
};
:::warning
禁用后以下功能失效：
- Logger 自动注入
requestId
app.throw() 自动解析请求级 localeapp.fetch() 自动传播 requestId
:::
VextFrontendConfig
内置前端构建与静态服务配置。
export default {
frontend: {
enabled: true,
framework: "react",
publicDir: "public",
publicPath: "/",
spaFallback: {
scopes: [
{
basePath: "/admin/app",
page: "admin/app/shell",
exclude: ["/admin/api/**"],
},
],
},
},
};
默认 spaFallback.scopes 为空，因此未知 HTML 路径不会被自动吞成 SPA 页面。需要混合 SSR + client-router 子应用时，在 scopes[] 中声明具体 basePath。spaFallback: true 仅作为兼容 shorthand，不推荐在企业级混合项目中使用。
VextClusterConfig
Cluster 多进程配置。完整接口定义见 src/types/app.ts VextClusterConfig。
基础字段
healthCheck — 心跳检测
reload — 零停机滚动重启
cluster.reload 只配置 vext reload / SIGHUP 触发滚动重启时的时间参数。省略 cluster.reload 不会禁用滚动重启，框架会使用默认值。
export default {
cluster: {
enabled: true,
workers: "auto", // 使用 availableParallelism / cgroup v1 / os.cpus 检测可用 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
路由级响应缓存全局配置。
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,
},
server: {},
response: {
hideInternalErrors: true,
wrap: true,
},
session: {
enabled: false,
name: 'vext.sid',
ttl: 86400,
rolling: false,
autoCommit: true,
idLength: 32,
cookie: {
httpOnly: true,
sameSite: 'lax',
path: '/',
secure: 'auto',
},
},
csrf: {
enabled: false,
mode: 'auto',
methods: ['POST', 'PUT', 'PATCH', 'DELETE'],
headerNames: ['x-csrf-token', 'x-xsrf-token'],
bodyField: '_csrf',
cookie: {
name: 'vext.csrf',
httpOnly: false,
sameSite: 'lax',
path: '/',
secure: 'auto',
},
fetchMetadata: true,
origin: false,
},
securityHeaders: {
enabled: false,
preset: 'basic',
},
bodyParser: {
enabled: true,
maxBodySize: '1mb',
},
accessLog: {
enabled: true,
level: 'info',
skipPaths: [],
},
openapi: {
enabled: false,
},
requestContext: {
enabled: true,
},
frontend: {
enabled: false,
},
}
VextUserConfig
用户配置的输入类型，所有字段均为可选。由 loadConfig() 合并默认值后生成完整的 VextConfig。
import type { VextUserConfig } from "vextjs";
const config: VextUserConfig = {
port: 8080,
logger: { level: "debug" },
};
export default config;
VextSessionConfig
config.session.enabled: true 会在生产、开发、测试和软重载链路中自动注册 Session。显式 session() 中间件仅用于作用域化或手动注册场景。
VextSessionCookieOptions 基于 CookieSerializeOptions，并额外支持 secure: boolean | "auto"。Cookie 选项包含 domain、path、expires、maxAge、httpOnly、secure、sameSite、priority、partitioned 与 encode。
VextSessionStore 必须实现 get(id)、set(id, data, ttlSeconds) 和 delete(id)。可选方法包括 touch(id, ttlSeconds)、clearExpired() 与 close()。配置 Store 和已启用的手动 Session 运行时会在应用关闭时调用 close()。
生产 cache-backed session 推荐使用 vextjs 根入口导出的 createCacheSessionStore(cacheLike, options?)。它接收具备 get、set、del 的结构型 VextCacheLike，把 session TTL 秒转换为 cache 毫秒，默认写入 JSON string，且只有传入 options.close 时才暴露 close()。config.cache.cacheHub 仍然只是路由响应缓存配置，不会注入 Session Store。
RouteOptions.session 接受 false、true 或 { enabled?, rolling?, autoCommit? }，可为单个路由关闭 Session，也可在全局运行时关闭时单独启用。
VextCsrfConfig
config.csrf 用于配置内置 CSRF 中间件。enabled: true 会在 body parsing 与插件全局中间件之后自动全局注册 CSRF；也可以保持禁用，并手动注册 csrf() 保护指定路径。
路由可通过 route options { csrf: false } 跳过 CSRF。
config.securityHeaders 用于启用 Vext 内置浏览器安全响应头。默认关闭。preset: "basic" 是多数应用的低破坏主路径；strict 与 custom 都是显式 opt-in。
export default {
securityHeaders: {
enabled: true,
preset: "basic",
contentSecurityPolicy: {
reportOnly: true,
directives: {
"default-src": ["'self'"],
"upgrade-insecure-requests": true,
},
},
},
};
basic 发送 X-Content-Type-Options: nosniff、Referrer-Policy: strict-origin-when-cross-origin 与 X-Frame-Options: SAMEORIGIN。strict 额外开启 HTTPS-only HSTS、最小 Permissions-Policy、COOP 和 CORP，但 CSP 与 COEP 仍需显式配置。custom 只发送你配置的字段。路由可通过 { securityHeaders: false } 跳过。
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 < config profile < local < bootstrap provider patch < CLI override。
环境变量覆盖
部分配置支持通过环境变量覆盖：
VEXT_PORT=8080 VEXT_CONFIG=sg-sit 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,
},
};
