# VextJS 完整简体中文文档索引

> 由全部公开简体中文文档源生成；每个 canonical URL 只出现一次，并带有从源文档提取的摘要。

## 简体中文文档

- [VextJS](https://devcodex-labs.github.io/vextjs/zh/): 用一个 Node.js 应用交付 API 与服务端渲染 React 页面，并统一路由模型、类型契约和内置文档。
- [Access Log 中间件](https://devcodex-labs.github.io/vextjs/zh/api/access-log): VextJS 内置 Access Log 中间件，自动记录每个 HTTP 请求的方法、路径、状态码、响应时间和客户端 IP。该中间件基于洋葱模型（after-middleware 模式），在请求处理完成后输出一行紧凑的访问日志。
- [应用实例](https://devcodex-labs.github.io/vextjs/zh/api/app): 本页详细介绍 VextJS 的应用实例 VextApp 的完整 API，包括内置模块、扩展方法、生命周期钩子和启动函数。
- [配置项](https://devcodex-labs.github.io/vextjs/zh/api/config): 本页详细列出 VextJS 的所有配置字段、类型、默认值及使用说明。
- [请求与响应](https://devcodex-labs.github.io/vextjs/zh/api/context): 本页详细介绍 VextJS 的请求对象 VextRequest 和响应对象 VextResponse 的完整 API。
- [Fetch API](https://devcodex-labs.github.io/vextjs/zh/api/fetch): 本页提供 app.fetch 内置 HTTP 客户端的精简 API 参考。完整的使用指南、示例和最佳实践请参阅 内置 HTTP 客户端指南。
- [插件 API](https://devcodex-labs.github.io/vextjs/zh/api/plugin-api): 本页详细介绍 VextJS 的插件系统 API，包括插件定义、中间件定义辅助函数和相关类型。
- [路由定义](https://devcodex-labs.github.io/vextjs/zh/api/route-definition): 本页详细介绍 VextJS 的路由定义 API，包括 defineRoutes、路由选项、参数校验、中间件引用和文档配置。
- [测试工具](https://devcodex-labs.github.io/vextjs/zh/api/testing-api): 本页详细介绍 VextJS 的测试工具 API，包括 createTestApp、TestApp、TestRequest、TestRequestBuilder 和 TestResponse。
- [性能基准测试](https://devcodex-labs.github.io/vextjs/zh/benchmark): 本页展示 VextJS 与其他主流 Node.js Web 框架的性能基准对比数据。当前版本的可复现基准以仓库内 test/benchmark/run-benchmark.mjs 为准；页面中的历史 benchmark 仓库数据仅用于趋势参考。
- [CRUD API](https://devcodex-labs.github.io/vextjs/zh/examples/crud-api): 一个完整的 RESTful CRUD API 示例，展示 VextJS 的服务层、中间件、参数校验、错误处理等核心能力。
- [Hello World](https://devcodex-labs.github.io/vextjs/zh/examples/hello-world): 最简单的 VextJS 项目，帮助你理解框架的基本结构和工作方式。
- [Nacos 接入示例](https://devcodex-labs.github.io/vextjs/zh/examples/nacos-integration): 本示例演示如何在 VextJS 中集成 Nacos，实现服务注册与发现、运行期动态配置，以及启动期远程配置补丁。
- [OpenTelemetry 可观测性](https://devcodex-labs.github.io/vextjs/zh/examples/opentelemetry): 本文档只介绍 VextJS 场景下如何接入 @devcodex/opentelemetry。
- [permission-core Auth 接入](https://devcodex-labs.github.io/vextjs/zh/examples/permission-core-auth): 本示例展示如何把 permission-core 接入 VextJS Auth。Vext 的认证与路由保护是分层的：
- [API Client 与契约](https://devcodex-labs.github.io/vextjs/zh/frontend/api-client-and-contracts): Vext 页面首屏数据不需要生成 API client。首屏数据应优先使用 route handler 和 res.render()。
- [边界与路线图](https://devcodex-labs.github.io/vextjs/zh/frontend/boundaries-and-roadmap): 本页区分当前前端目标和后续能力方向。
- [构建与发布](https://devcodex-labs.github.io/vextjs/zh/frontend/build-and-deploy): vext build 会在一个命令中编译服务端产物和前端产物。本页给出生产交付路径；字段级说明见前端配置，缓存和媒体行为见静态资源与 CDN。
- [构建、发布与性能](https://devcodex-labs.github.io/vextjs/zh/frontend/build-deploy-performance): 本页仅为旧链接保留。
- [代码拆分](https://devcodex-labs.github.io/vextjs/zh/frontend/code-splitting): Vext 围绕页面、layout、错误页、locale 和共享 runtime chunk 拆分前端代码。
- [前端配置](https://devcodex-labs.github.io/vextjs/zh/frontend/configuration): 本页是决策指南，不重复罗列每一个类型成员。先使用默认值，只为产品确实要改变的行为配置字段；需要精确字段、默认值或嵌套选项时，以VextFrontendConfig API 参考为准。
- [CSR 与 SPA Fallback](https://devcodex-labs.github.io/vextjs/zh/frontend/csr-and-spa-fallback): Vext 默认页面模型是 SSR + hydration。CSR fallback 必须显式、范围化配置。
- [数据与 API 调用](https://devcodex-labs.github.io/vextjs/zh/frontend/data-and-api): 本页仅为旧链接保留。
- [数据流](https://devcodex-labs.github.io/vextjs/zh/frontend/data-flow): Vext 前端数据从服务端开始。Route handler 调用 services，准备 JSON-safe 数据，再传给 res.render()。
- [开发工作流](https://devcodex-labs.github.io/vextjs/zh/frontend/dev-workflow): vext dev 会同时启动后端 runtime 和前端开发流水线。前端输出写入 .vext/client/。
- [诊断与 Leak Scan](https://devcodex-labs.github.io/vextjs/zh/frontend/diagnostics-and-leak-scan): Leak Scan 用来阻止服务端模块意外进入浏览器 bundle。
- [错误页与 Document](https://devcodex-labs.github.io/vextjs/zh/frontend/errors-and-document): 默认错误页放在：
- [Fast Refresh](https://devcodex-labs.github.io/vextjs/zh/frontend/fast-refresh): Fast Refresh 是 vext dev 中 React 页面、layout 和组件修改的默认反馈路径。
- [快速开始](https://devcodex-labs.github.io/vextjs/zh/frontend/getting-started): 本页是使用内置前端能力把 Vext 全栈页面跑起来的最短路径。
- [Hydration](https://devcodex-labs.github.io/vextjs/zh/frontend/hydration): Hydration 会把浏览器端 React tree 接到 SSR 产出的 HTML 上。
- [Hydration 验证](https://devcodex-labs.github.io/vextjs/zh/frontend/hydration-validation): Hydration 验证证明构建出的页面能在真实浏览器工作，而不只是静态产物存在。
- [前端多语言](https://devcodex-labs.github.io/vextjs/zh/frontend/i18n): 后端 config.locale 仍是全栈 locale 基础。frontend.i18n 负责前端页面文案和 hydration 行为。
- [Vext JSCSS](https://devcodex-labs.github.io/vextjs/zh/frontend/jscss): Vext JSCSS 会在构建期把 TypeScript 对象转换为 CSS class。组件需要有名字的 variants、语义化 CSS variables 或嵌套规则，同时希望浏览器最终加载的是 CSS 而不是 CSS-in-JS runtime 时，就使用它。
- [Layout 与组件](https://devcodex-labs.github.io/vextjs/zh/frontend/layouts-and-components): Vext layout 是 src/frontend/pages/ 下命名为 layout.tsx 的 React 组件。
- [前端总览](https://devcodex-labs.github.io/vextjs/zh/frontend/overview): 本前端指南描述 Vext 当前内置前端能力：route 驱动 React 19 页面、SSR、hydration、嵌套 layout、前端多语言、Fast Refresh、render refresh、代码拆分、静态资源、CDN 上传、性能预算和 hydration 验证。
- [页面与渲染](https://devcodex-labs.github.io/vextjs/zh/frontend/pages-and-rendering): 本页仅为旧链接保留。
- [性能预算](https://devcodex-labs.github.io/vextjs/zh/frontend/performance-budgets): 性能预算用于让 React hydration 路线可测、可控。
- [项目结构](https://devcodex-labs.github.io/vextjs/zh/frontend/project-structure): 默认 vext create 脚手架是全栈项目。前端源码统一放在 src/frontend/，让服务端代码和浏览器代码保持物理边界。
- [Render Data 与缓存](https://devcodex-labs.github.io/vextjs/zh/frontend/render-data-and-cache): Render data 是服务端准备、用于生成 HTML 并支持 hydration 的 payload。
- [Render Refresh](https://devcodex-labs.github.io/vextjs/zh/frontend/render-refresh): Render Refresh 处理会影响 res.render() HTML 输出的服务端变更。
- [渲染模式](https://devcodex-labs.github.io/vextjs/zh/frontend/rendering-modes): Vext 支持混合全栈前端模型，同时避免服务端文件进入浏览器 bundle。
- [路由与页面](https://devcodex-labs.github.io/vextjs/zh/frontend/routing-and-pages): Vext 的 URL 入口仍然属于 src/routes/。页面文件是渲染目标，不是自动 URL 定义。
- [SSR](https://devcodex-labs.github.io/vextjs/zh/frontend/ssr): 服务端渲染是 Vext 默认页面路径。Route handler 拥有 URL 与数据准备，前端页面拥有 React view。
- [静态资源与 CDN](https://devcodex-labs.github.io/vextjs/zh/frontend/static-assets-and-cdn): Vext 有两个静态资源位置，它们行为不同。
- [样式与资源](https://devcodex-labs.github.io/vextjs/zh/frontend/styles-and-assets): 全局 CSS 可以放在 src/frontend/styles/，并由页面、layout 或生成入口引用。
- [排错](https://devcodex-labs.github.io/vextjs/zh/frontend/troubleshooting): 如果 res.render("dashboard") 找不到页面，检查：
- [Adapter 架构](https://devcodex-labs.github.io/vextjs/zh/guide/adapters): VextJS 的核心设计之一是 Adapter 架构——底层 HTTP 处理层完全可替换。你的业务代码（路由、中间件、服务、插件）操作的是 VextJS 封装的 req / res 对象，而非底层框架的原生对象。切换 Adapter 仅需修改一行配置，业务代码零改动。
- [构建 (vext build)](https://devcodex-labs.github.io/vextjs/zh/guide/build): vext build 会将服务端源码编译为可部署的 JavaScript 产物；当 frontend.enabled 为 true 时，还会把浏览器客户端打包到 dist/client/。当前版本的 vext build 按 production-target build 设计：它会对用户源码中的 process.env.NODEENV 做生产模式静态注入；运行时实际加载哪个配置 profile，由 vext start --config <name 或 VEXTCONFIG=<name 决定。基于 esbu...
- [响应缓存](https://devcodex-labs.github.io/vextjs/zh/guide/cache): VextJS 提供声明式路由级响应缓存，通过路由选项的 cache 字段配置。缓存命中时跳过参数校验和 handler 执行，直接返回已缓存的 JSON 响应。
- [CLI 命令](https://devcodex-labs.github.io/vextjs/zh/guide/cli): VextJS 提供了 vext 命令行工具，覆盖项目创建、开发、构建、部署的完整生命周期。
- [Cluster 多进程](https://devcodex-labs.github.io/vextjs/zh/guide/cluster): VextJS 内置 Cluster 多进程管理，通过 ClusterMaster 管理多个 Worker 进程，充分利用多核 CPU，并支持零停机滚动重启、心跳检测、自动故障恢复等企业级特性。
- [配置](https://devcodex-labs.github.io/vextjs/zh/guide/configuration): VextJS 采用 多层配置合并 机制，支持按环境覆盖配置，同时提供丰富的内置配置项覆盖框架行为。
- [Cookies 与 Sessions](https://devcodex-labs.github.io/vextjs/zh/guide/cookies-session): Vext 提供一等 cookie 解析、响应 cookie 辅助方法和配置驱动的 Session 运行时。该能力零第三方依赖，并覆盖 Native、Hono、Fastify、Express、Koa adapter。
- [zh/guide/database](https://devcodex-labs.github.io/vextjs/zh/guide/database): VextJS 内置了 MonSQLize 数据库插件，提供开箱即用的 MongoDB 数据库支持。只需在配置文件中添加 database 字段，框架会自动完成连接管理、Model 加载和资源清理。
- [部署与生产环境](https://devcodex-labs.github.io/vextjs/zh/guide/deployment): 本指南介绍如何将 VextJS 应用部署到生产环境，涵盖构建、Docker 容器化、Nginx 反向代理、PM2 进程管理、日志收集和健康检查等实践。
- [错误处理](https://devcodex-labs.github.io/vextjs/zh/guide/error-handling): VextJS 会统一捕获 route、middleware 和 service 中抛出的异常，并转换成 HTTP 响应。主动返回业务错误时优先使用 app.throw(...)；字段级校验失败使用 VextValidationError；未预期异常才直接 throw new Error(...)。
- [内置 HTTP 客户端 (app.fetch)](https://devcodex-labs.github.io/vextjs/zh/guide/fetch): VextJS 内置了增强版 HTTP 客户端 app.fetch，基于 Node.js 20+ 原生 fetch 封装，提供 requestId 自动传播、超时控制、自动重试、结构化日志、create() 工厂 和 config 驱动代理 等能力。无需安装任何第三方 HTTP 库即可进行服务间调用。
- [前端集成](https://devcodex-labs.github.io/vextjs/zh/guide/frontend): 本页仅为历史链接保留。
- [运行时 Hooks](https://devcodex-labs.github.io/vextjs/zh/guide/hooks): app.hooks.on(name, handler) 用来观察或轻量 patch 框架运行时生命周期。它适合做请求审计、校验通过后的请求记录、响应 header patch、出站调用监控、service 调用追踪、OpenAPI 文档补丁等横切逻辑。
- [热重载](https://devcodex-labs.github.io/vextjs/zh/guide/hot-reload): VextJS 内置智能热重载机制，通过 vext dev 命令启动开发模式。框架会监听文件变更，根据变更类型自动选择最优的重载策略，从毫秒级的热替换到完整的进程重启，覆盖所有开发场景。
- [国际化 (i18n)](https://devcodex-labs.github.io/vextjs/zh/guide/i18n): VextJS 内置国际化支持，通过 src/locales/ 目录下的语言包文件，实现错误消息的多语言翻译。语言包由 i18n-loader 自动扫描加载，与 app.throw() 和 schema-dsl 校验系统无缝联动。
- [介绍](https://devcodex-labs.github.io/vextjs/zh/guide/introduction): VextJS 是一个面向 API、服务端渲染 React 页面或两者并存场景的 Node.js 全栈框架。src/routes/ 始终拥有 URL，服务、校验、安全、缓存、OpenAPI 与类型客户端共用同一套请求契约。你可以从默认全栈脚手架起步，也可以保持 API-only，而不必引入第二套路由模型。
- [日志 (Logger)](https://devcodex-labs.github.io/vextjs/zh/guide/logger): VextJS 内置零 runtime dependency 的 Vext logger kernel，通过 app.logger 在框架的任意位置使用。默认提供结构化 JSON、pretty/JSON 双模式、pretty level 彩色输出、requestId 自动注入、child logger、运行时级别控制和极简日志脱敏等能力。
- [中间件](https://devcodex-labs.github.io/vextjs/zh/guide/middleware): VextJS 的中间件采用 洋葱模型（Onion Model），支持请求前处理和响应后处理。框架提供 defineMiddleware 和 defineMiddlewareFactory 两种定义方式，通过约定式目录自动扫描加载。
- [OpenAPI 文档](https://devcodex-labs.github.io/vextjs/zh/guide/openapi): VextJS 内置 OpenAPI 文档自动生成功能。基于路由的 validate 和 docs 配置，框架自动生成 OpenAPI 3.0 规范 JSON，并通过 Vext Docs Renderer 提供默认 /docs 文档页。第三方文档工具请直接消费 /openapi.json。
- [插件](https://devcodex-labs.github.io/vextjs/zh/guide/plugins): VextJS 的插件系统是框架的唯一扩展入口。通过插件，你可以向 app 对象注入自定义能力、注册全局中间件、替换内置实现、管理资源生命周期。
- [预加载（Preload）](https://devcodex-labs.github.io/vextjs/zh/guide/preload): VextJS 提供了 预加载（Preload） 机制，允许以下两类来源在 Node.js 模块加载之前执行脚本：
- [项目结构](https://devcodex-labs.github.io/vextjs/zh/guide/project-structure): VextJS 遵循 约定优于配置 的设计理念，通过固定的目录结构实现自动扫描、加载和注册，无需手动配置路由映射或服务注入。
- [快速开始](https://devcodex-labs.github.io/vextjs/zh/guide/quick-start): VextJS 提供 vext create 命令创建可运行项目。默认模板会直接证明一套路由模型：/ 通过 res.render() 渲染 React，/api/hello 返回 JSON，两者都调用生成的 example service；不需要页面运行时则选择 API-only。
- [请求上下文 (Request Context)](https://devcodex-labs.github.io/vextjs/zh/guide/request-context): VextJS 基于 Node.js AsyncLocalStorage 实现了请求级上下文存储 requestContext，为每个请求维护独立的上下文数据。无需手动传参，在路由、中间件、服务、插件的任意深层代码中都能访问当前请求的上下文信息。
- [路由](https://devcodex-labs.github.io/vextjs/zh/guide/routing): VextJS 采用 约定式文件路由 + 三段式路由定义，将文件路径自动映射为 URL 前缀，在文件内部通过 defineRoutes() 声明具体路由。
- [服务层](https://devcodex-labs.github.io/vextjs/zh/guide/services): VextJS 采用 分层架构，将业务逻辑集中在服务层（Service Layer）。服务文件放在 src/services/ 目录下，由框架自动扫描、实例化并注入到 app.services，路由 handler 中通过 app.services.xxx 访问。
- [测试](https://devcodex-labs.github.io/vextjs/zh/guide/testing): VextJS 内置了完整的测试工具，通过 vextjs/testing 子路径导入。无需启动真实 HTTP 服务器，即可对路由、中间件、服务进行端到端测试。
- [参数校验](https://devcodex-labs.github.io/vextjs/zh/guide/validation): VextJS 集成 schema-dsl，提供声明式参数校验。在路由 options.validate 中用简洁的 DSL 字符串描述校验规则，框架自动完成校验、类型转换，并同步生成 OpenAPI 文档。
- [文档数据与 AI](https://devcodex-labs.github.io/vextjs/zh/resources/documentation-data-and-ai): 面向 VextJS 的 canonical、机器可读文档资产，以及隐私优先的度量边界。
- [支持与服务](https://devcodex-labs.github.io/vextjs/zh/resources/support-and-services): 面向生产评审、迁移实施与团队赋能的 maintainer 参与式范围沟通入口。