#前端配置

本页帮助你在已有全栈应用中修改配置。先完成快速开始，再将所需字段合并到 src/config/default.ts，保留已有的服务端设置。先使用默认值，只为产品确实要改变的行为配置字段；完整类型成员见VextFrontendConfig API 参考。

#目录导航

• 最小配置
• 决定要配置什么
• 完整示例
• 生产交付配置形态
• 核心字段
• Render 字段
• Style 字段
• Build 字段
• Deploy 字段
• SEO 字段
• I18n 字段
• Dev 字段
• SPA Fallback 字段
• 验证配置变更

#最小配置

在默认配置中启用前端；页面文件和路由仍需按快速开始准备：

import type { VextConfigOverride } from "vextjs";

export default {
  frontend: true,
} satisfies VextConfigOverride;

frontend: true 使用 src/frontend、pages、components、styles/index.css 与 public 约定。改成对象形式时，需要显式写 enabled: true；对象本身不表示启用。生产默认前端输出为 dist/client，浏览器压缩开启、source map 关闭；SSR renderer 是独立 Node bundle，默认不压缩。

完全关闭前端可将字段改为 frontend: false。同时删除或调整依赖 res.render() 的 handler；关闭配置不会自动清除旧生成目录。

#决定要配置什么

不要因为字段存在就添加它。全局默认使用 React + esbuild、SSR 开启、buffered streaming、浏览器代码拆分开启、生产浏览器压缩开启，且没有 CDN 地址、上传默认关闭（默认上传 adapter 是 filesystem）。全栈模板另外显式配置了 streaming: auto 和前端国际化；以应用实际配置为准。

#完整示例

以下是可用于默认全栈模板的同源配置对象，展示各字段的层级；大多数值与默认一致，不要求全部手写。预算数字仅作演示，先以 warnOnly: true 收集数据。模板已有 en-US 词典，因此示例显式开启前端国际化。

import type { VextConfigOverride } from "vextjs";

export default {
  frontend: {
    enabled: true,
    framework: "react",
    root: "src/frontend",
    publicDir: "public",
    publicPath: "/",
    styles: {
      jscss: { enabled: true },
    },
    dev: {
      hot: true,
      fastRefresh: true,
      renderRefresh: "prompt",
    },
    build: {
      target: "es2022",
      minify: true,
      sourcemap: false,
      client: {
        external: [],
        externalRuntime: {},
      },
      vendorChunks: {
        enabled: true,
        packages: ["react", "react-dom", "react-dom/client"],
      },
      assets: {
        inlineLimit: 0,
      },
      css: {
        modules: true,
      },
      budgets: {
        warnOnly: true,
        maxInitialJsBrotliBytes: 60_000,
        maxRouteInitialJsBrotliBytes: 80_000,
        maxAppOwnedInitialJsBrotliBytes: 40_000,
      },
      diagnostics: {
        leakScan: true,
        performanceReport: true,
      },
    },
    i18n: {
      enabled: true,
      defaultLocale: "en-US",
      clientLoad: "current",
    },
    spaFallback: {
      scopes: [],
    },
    apiClient: true,
  },
} satisfies VextConfigOverride;

#生产交付配置形态

#同源（默认）

首次生产部署不需要配置 CDN：

export default {
  frontend: true,
};

vext build 会写出配套的前端 manifest、浏览器资源和 SSR renderer；vext start 会检查这些生产产物，并由同一个 Node 服务同时提供资源与 SSR 页面。输出目录有定制时以解析后的路径为准，详见构建指南。

#CDN 与增量上传

已经有可用 CDN 时，再合并下面的可选配置。先把示例域名替换为实际资源地址；直接复制示例域名会让浏览器无法加载所需资源。

export default {
  frontend: {
    enabled: true,
    deploy: {
      assetBaseUrl: "https://cdn.example.com/my-app/",
      integrity: true,
      upload: {
        enabled: true,
        adapter: "filesystem",
        targetDir: ".vext/frontend-cdn",
        stateFile: ".vext/deploy/frontend-assets-state.json",
        exclude: ["**/*.map"],
      },
    },
  },
};

filesystem 只把选定资源复制到本地 staging 目录，不会把文件自动发布到示例域名；云端交付需使用自定义 adapter 或既有发布流程。把 state file 放在 frontend.outDir 外，先构建，再执行 vext deploy assets --dry-run 检查计划；dry-run 不上传资源。实际资源就绪后再部署同次构建的 Node 输出。完整步骤见静态资源与 CDN。

#核心字段

目录字段的相对基准与 TypeScript paths 同步见项目结构。支持的图片与字体 import 在浏览器和 SSR 构建中共用公开 URL；alias 只改变解析路径。

#Render 字段

渲染基础见SSR，模式选择见渲染模式。同步 SSR 的超时是在渲染返回后检查，不会抢占同步 JavaScript 执行；流式响应开始发送后的失败也不能按普通 buffered 响应重写。关闭 SSR 与关闭浏览器 hydration 是不同设置，后者见Hydration。

#Style 字段

#Build 字段

React 相关 browser external 必须提供 externalRuntime 映射，否则构建会用友好诊断失败。

浏览器输出采用目录模式，通过 frontend.outDir 配置；不支持 frontend.build.client.outFile。Vext 始终生成 SSR、preload、deploy 和验证所需的 frontend manifest family，因此 build.client.manifest / build.server.manifest 不是配置字段。

普通产品应保持浏览器代码拆分、hash 命名和 Vext-managed vendor entry 开启。先以 warning 形式配置预算，检查 size-report.json 中的完整 route closure，再把预算转成 release 阻断门禁。

#Deploy 字段

glob 配置（例如部署 include/exclude、媒体扫描与样式 include）统一限制为每组最多 1024 个 pattern、单个最长 4096 字符、括号嵌套最多 100 层、单个 brace 展开估计最多 4096 项。超出时在调用匹配器前报错；这是输入预算保护，上游 braces 的审计项仍需等待修复。

assetBaseUrl 必须是绝对 URL。deploy-manifest.json 描述本次可交付的 JS、CSS、已产出的媒体和选中的 public 文件；生成清单本身不会上传。默认排除 source map，SSR renderer 和入口 HTML 不作为 CDN 上传资源。每次更换 adapter、prefix 或 include/exclude 规则前，都要先执行 npx vextjs deploy assets --dry-run。

#SEO 字段

frontend.seo 是全局 SEO 配置入口；配置该对象后，enabled 默认是 true。未配置该对象时，显式 route/render SEO 仍可生效；sitemap/robots 需要各自配置。显式 enabled: false 关闭结构化 SEO，legacy head 仍独立生效。

import type { VextConfigOverride } from "vextjs";

export default {
  frontend: {
    enabled: true,
    seo: {
      publicOrigin: process.env.PUBLIC_ORIGIN ?? "https://www.example.com",
      titleTemplate: "%s | Example",
      defaults: { description: "Example 应用" },
      sitemap: {},
      robots: {},
    },
  },
} satisfies VextConfigOverride;

使用前将 publicOrigin 换成真实公开 origin。未显式覆盖 canonical 时，Vext 会结合请求 pathname 生成页面 URL。静态元数据放在路由级 frontend.seo；依赖页面数据的元数据放在 res.render(..., { seo })。sitemap 与 robots 均可选择 "build" 或 "runtime" 模式，空对象默认 build；有限多域名部署使用命名 origins。

动态 canonical、provider、Host 选择、产物与无 hydration 示例见 SEO、Sitemap 与 Robots，完整嵌套字段见 API 参考。

#I18n 字段

完整可运行示例与语言优先级、SSR/浏览器加载及缓存边界见前端多语言。inject: "used" 和 clientSwitch 的保留行为在该页单独说明。

#Dev 字段

frontend.dev.overlay 只控制前端浏览器开发 UI。后端异常 HTML overlay 由顶层 dev.errorOverlay 单独配置。

#SPA Fallback 字段

应声明单独 scope，而不是全站 catch-all。API、OpenAPI 和文档路由默认被排除，避免 client-router shell 遮住运维 endpoint。

spaFallback: true 是一个特别分支：它创建根路径 /、page 为 index 的 scope；不等于省略配置。自定义全局 exclude 会替换默认数组，需自行保留所需排除项。Fallback 还受请求方法、Accept 和已有路由等条件约束，详见CSR 与 SPA Fallback。未生成 SSR 正文的 shell 使用 createRoot；完成 SSR 的页面使用 hydrateRoot。

#验证配置变更

# 默认 TypeScript 模板包含类型检查，并构建后端、浏览器与 SSR。
npm run build

# 若启用了 upload，只预览计划，不上传。
npx vextjs deploy assets --dry-run

# 启动配套生产产物。
npm start -- --port 3000

先停止占用端口的开发服务；没有配置 upload 时跳过 dry-run 命令。同源示例应保留快速开始中的页面正文与可加载资源。修改 build 或 budget 后，检查当前输出目录的 size-report.json；warnOnly: true 允许超预算告警，未设该项且超出启用的预算会使构建失败。修改 CDN 后，请求一个 SSR 页面和其实际引用的浏览器资源，确认来自同次构建；实际 CDN 可达性需在真实部署环境验证。修改 SPA fallback 后，既验证 scope 内路径，也请求明确排除的 API 路径。验证后按 Ctrl+C 停止服务。较少使用的嵌套字段以API 参考为准。