前端配置

目录导航

最小配置

export default {
  frontend: true,
};

完全关闭前端:

export default {
  frontend: false,
};

完整示例

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: {
        maxInitialJsBrotliBytes: 60_000,
        maxRouteInitialJsBrotliBytes: 80_000,
        maxAppOwnedInitialJsBrotliBytes: 40_000,
      },
      diagnostics: {
        leakScan: true,
        performanceReport: true,
      },
    },
    deploy: {
      assetBaseUrl: "https://cdn.example.com/my-app/",
      crossOrigin: "anonymous",
      integrity: true,
      upload: {
        enabled: true,
        adapter: "filesystem",
        targetDir: ".vext/frontend-cdn",
        publicBaseUrl: "https://cdn.example.com/my-app/",
        prefix: "my-app",
        stateFile: ".vext/deploy/frontend-assets-state.json",
        exclude: ["**/*.map"],
      },
    },
    i18n: {
      enabled: true,
      defaultLocale: "en-US",
      clientLoad: "current",
    },
    spaFallback: {
      scopes: [],
    },
    apiClient: true,
  },
};

核心字段

字段默认值含义
frontend.enabledfalse启用内置前端流水线
frontend.framework"react"内置 React 支持的框架标签
frontend.root"src/frontend"用户前端源码根目录
frontend.indexHtmlsrc/frontend/pages/_document.htmlDocument 模板
frontend.outDirdev 为 .vext/client,build 为 dist/client前端输出目录
frontend.publicDir"public"公共静态资源目录
frontend.publicPath"/"公开资源 URL 前缀

Style 字段

字段默认值含义
frontend.styles.entrystyles/index.cssfrontend.root 解析的全局 CSS 入口
frontend.styles.jscss.enabledtrue启用 Vext JSCSS 抽取
frontend.styles.jscss.files**/*.style.ts, **/*.style.js, **/*.css.tsJSCSS source globs
frontend.styles.jscss.runtimeAdaptercss-variables以 CSS custom properties 输出动态变量;none/false 使用 fallback 值
frontend.styles.jscss.dynamicVarstrue输出 custom property 声明与 var(...) 引用
frontend.styles.jscss.recipestrue输出 recipe variant class 与 rules

Build 字段

字段默认值含义
frontend.build.target"es2022"传给 esbuild 的浏览器目标
frontend.build.minify生产期 true压缩浏览器产物
frontend.build.sourcemap开发期 true生成 source map
frontend.build.client.assetsDir"assets"浏览器 bundle 资源子目录
frontend.build.client.splittingtrue启用浏览器代码拆分
frontend.build.client.external[]浏览器 external 模块
frontend.build.client.externalRuntime{}浏览器 external 的 import-map URL
frontend.build.server.outFileserver/renderer.cjsfrontend.outDir 下的 SSR renderer bundle 文件
frontend.build.vendorChunksenabled共享 runtime chunk 策略
frontend.build.assets.inlineLimit0小于该字节数的 import 型资源内联
frontend.build.css.modulestrue启用 CSS Modules
frontend.build.diagnostics.leakScantrue阻断服务端模块进入浏览器 graph
frontend.build.diagnostics.sizeReporttrue写入 size-report.json
frontend.build.diagnostics.performanceReporttrue包含路由级性能指标

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

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

Deploy 字段

字段默认值含义
frontend.deploy.assetBaseUrlCDN / public asset base URL
frontend.deploy.crossOrigin生成标签的 crossorigin
frontend.deploy.integrityfalse为生成 JS/CSS 添加 SRI integrity
frontend.deploy.upload.enabledfalse启用 vext build --upload-assets / vext deploy assets 上传
frontend.deploy.upload.adapterfilesystemmock 或自定义 adapter
frontend.deploy.upload.stateFile.vext/deploy/...增量上传状态文件
frontend.deploy.upload.exclude["**/*.map"]不上传的文件

I18n 字段

字段默认值含义
frontend.i18n.enabledtrue扫描并打包前端页面文案
frontend.i18n.defaultLocale后端默认 locale前端 fallback locale
frontend.i18n.clientLoad"current"浏览器 locale 加载模式
frontend.i18n.htmlLangtrue写入请求级 {vext.lang} / <html lang>

Dev 字段

字段默认值含义
frontend.dev.hottrue启用前端 dev events
frontend.dev.fastRefreshtrue尽可能启用 React Fast Refresh
frontend.dev.overlaytrue显示前端 rebuild 错误与 render refresh 浏览器提示 UI
frontend.dev.renderRefresh"prompt"render-data 后端 reload 后的浏览器行为

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

SPA Fallback 字段

字段默认值含义
frontend.spaFallback.scopes[]显式 client-router 子应用 fallback 范围
frontend.spaFallback.exclude["/api/**", "/openapi.json", "/docs/**", "/_vext/docs/**"]fallback 永远不会接管的全局路径
scopes[].basePath必填shell 负责的 URL 前缀
scopes[].page必填src/frontend/pages/** 下的 shell page id
scopes[].ssrfalseshell 是否 SSR 渲染
scopes[].exclude[]不进入 fallback 的路径
scopes[].status200fallback 命中后的 HTTP status