> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# output.ssg

- **类型：** `boolean | object`
- **默认值：** `undefined`

开启应用 SSG 功能的配置

:::tip 开启 SSG 功能
此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/zh/guides/basic-features/render/ssg.md) 文档了解如何开启 SSG 功能及使用场景。

:::

:::info 前置阅读
SSG 功能使用与路由关联性较大，建议使用前先了解[路由方案](/zh/guides/basic-features/routes/routes.md)。

:::

:::info

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

:::

## Boolean 类型

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

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

## Object 类型

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

### 配置类型

```ts
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 旁生成路由参数](/zh/guides/basic-features/render/ssg.md#在-loader-旁生成路由参数)。

### 示例

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

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

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