For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/configure/app/output/ssg.md.
  • 简体中文
  • output.ssg

    • 类型: boolean | object
    • 默认值: undefined

    开启应用 SSG 功能的配置

    开启 SSG 功能

    此配置需要在开启 SSG 功能情况下才会生效。请阅读 静态站点生成 文档了解如何开启 SSG 功能及使用场景。

    前置阅读

    SSG 功能使用与路由关联性较大,建议使用前先了解路由方案。

    Info
    • 单入口建议使用 output.ssg。
    • 多入口建议优先使用 output.ssgByEntries。
    • 当 output.ssg 为 true 且未配置 output.ssgByEntries 时,所有入口都会启用 SSG,并遵循下文的路由收集规则。

    Boolean 类型

    当该配置设置为 true 时,将会默认开启所有入口的 SSG 功能。对自控式路由而言,将会渲染入口的根路由。对约定式路由而言,将会渲染非动态路由和页面级 ssgParams 生成的路径,未提供参数生成函数的动态路由会被跳过。

    export default defineConfig({
      output: {
        ssg: true,
      },
    });

    Object 类型

    当值类型为 Object 时,可以配置如下属性。

    配置类型

    type SSGRouteOptions =
      | string
      | {
          url: string;
          output?: string;
          headers?: Record<string, any>;
        };
    
    type SSGOptions = {
      headers?: Record<string, any>;
      routes?: SSGRouteOptions[];
    };

    路由收集

    • 不设置 routes 或设置为 [] 时,约定式路由会自动包含非动态路由,以及文件系统路由的 page.data.ts 或 $.data.ts 中 ssgParams 生成的路径。配置式路由不参与参数生成函数的发现。
    • routes 非空时,渲染显式列出的路径和 ssgParams 生成的路径,跳过其他非动态路由。两者得到同一个 URL 时只渲染一次,使用显式路由的 headers、output 等配置。
    • 将入口的 SSG 配置设为 false,也会禁用其参数生成函数。

    这些规则同样适用于通过 output.ssgByEntries 配置的各个入口。参数类型、编码规则和示例请参考在 Loader 旁生成路由参数。

    示例

    下面的示例配置中,SSG 会渲染 /、/about 和 /user/:id 三条路由对应的页面。

    对于 /user/:id 路由,会在请求头中添加 cookies,并指定具体的路径。

    modern.config.ts(单入口)
    export default defineConfig({
      output: {
        ssg: {
          routes: [
            '/',
            '/about',
            {
              url: '/user/modernjs',
              headers: {
                cookies: 'name=modernjs',
              },
            },
          ],
        },
      },
    });