您的项目配置位于项目根目录下的 `svelte.config.js` 文件中。此外，SvelteKit 也使用此配置对象，以及其他与 Svelte 集成的工具，如编辑器扩展。

```js
/// file: svelte.config.js
// @filename: ambient.d.ts
declare module '@sveltejs/adapter-auto' {
	const plugin: () => import('@sveltejs/kit').Adapter;
	export default plugin;
}

// @filename: index.js
// ---cut---
import adapter from '@sveltejs/adapter-auto';

/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		adapter: adapter()
	}
};

export default config;
```

## 
配置

扩展[`vite-plugin-svelte`的选项](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#svelte-options)。

```dts
interface Config extends SvelteConfig {/*…*/}
```

```dts
kit?: KitConfig;
```

SvelteKit 选项。

`[键：字符串]: 任何；`

任何需要与 Svelte 集成的工具所需的附加选项。

## 
套件配置

The `kit` 属性配置 SvelteKit，并可以具有以下属性：

## 
适配器

*   默认`未定义`

您的[适配器](/docs/kit/adapters)在执行`vite build`时运行。它决定了输出如何转换为不同的平台。

## 
别名

*   默认`{}`

一个包含零个或多个别名的对象，用于替换 `import` 语句中的值。这些别名将自动传递给 Vite 和 TypeScript。

```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		alias: {
			// this will match a file
			'my-file': 'path/to/my-file.js',

			// this will match a directory and its contents
			// (`my-directory/x` resolves to `path/to/my-directory/x`)
			'my-directory': 'path/to/my-directory',

			// an alias ending /* will only match
			// the contents of a directory, not the directory itself
			'my-directory/*': 'path/to/my-directory/*'
		}
	}
};
```

> \[!注意\] 内置的 `$lib` 别名由 `config.kit.files.lib` 控制，因为它用于打包。

> \[!注意\] 您需要运行 `npm run dev` 以使 SvelteKit 自动在 `jsconfig.json` 或 `tsconfig.json` 中生成所需的别名配置。

## appDir

*   默认`"_app"`

目录，其中 SvelteKit 存储其内容，包括静态资产（如 JS 和 CSS）以及内部使用的路由。

如果指定了 `paths.assets`，则会有两个应用程序目录 — `${paths.assets}/${appDir}` 和 `${paths.base}/${appDir}`。

## csp

[内容安全策略](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)配置。CSP 有助于保护您的用户免受跨站脚本（XSS）攻击，通过限制资源可以加载的位置。例如，这样的配置...

```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		csp: {
			directives: {
				'script-src': ['self']
			},
			// must be specified with either the `report-uri` or `report-to` directives, or both
			reportOnly: {
				'script-src': ['self'],
				'report-uri': ['/']
			}
		}
	}
};

export default config;
```

...将阻止从外部站点加载脚本。SvelteKit 将为它生成的任何内联样式和脚本添加非 ces 或散列（取决于`模式`）以增强指定的指令。

要手动为包含在`src/app.html`中的脚本和链接添加 nonce，您可以使用占位符`%sveltekit.nonce%`（例如 `<script nonce="%sveltekit.nonce%">` ）。

当页面预渲染时，通过一个`＜meta http-equiv＞`标签添加 CSP 头部（注意，在这种情况下，`frame-ancestors`、`report-uri`和`sandbox`指令将被忽略）。

> \[!注意\] 当 `模式` 为 `'自动'` 时，SvelteKit 将为动态渲染的页面使用非 ces，为预渲染的页面使用哈希。在预渲染的页面中使用非 ces 是不安全的，因此被禁止。

> \[!注意\] 注意，大多数 [Svelte 过渡](/tutorial/svelte/transition) 通过创建一个内联 `<style>` 元素来工作。如果您在您的应用程序中使用这些，您必须保留 `style-src` 指令未指定，或者添加 `unsafe-inline`。

如果此级别的配置不足，并且您有更多动态需求，可以使用[`handle`钩子](/docs/kit/hooks#Server-hooks-handle)来自定义您的 CSP。

```ts
// @noErrors
mode?: 'hash' | 'nonce' | 'auto';
```

是否使用哈希或 nonce 来限制`<script>`和`<style>`元素。`'auto'`将为预渲染页面使用哈希，为动态渲染页面使用 nonce。

```ts
// @noErrors
directives?: CspDirectives;
```

指令将添加到 `内容安全策略` 头部。

```ts
// @noErrors
reportOnly?: CspDirectives;
```

指令将添加到 `Content-Security-Policy-Report-Only` 头中。

## csrf

防护[跨站请求伪造（CSRF）攻击](https://owasp.org/www-community/attacks/csrf)。

```ts
// @noErrors
checkOrigin?: boolean;
```

*   默认`真`

是否检查 incoming `origin` 标头对于 `POST`、`PUT`、`PATCH` 或 `DELETE` 表单提交，并验证其是否与服务器原点匹配。

为了允许人们从其他来源向您的应用发送具有 `application/x-www-form-urlencoded` `Content-Type`的`POST`、`PUT`、`PATCH`或`DELETE`请求，其中`multipart/form-data`或`text/plain`，您需要禁用此选项。请小心！

## 
嵌入式

*   默认`否`

是或否将应用嵌入到更大的应用中。如果 `true`，SvelteKit 将在其父元素 `%sveltekit.body%` 上添加与导航等相关的监听器，而不是添加到 `window`，并且将从服务器传递 `params` 而不是从 `location.pathname` 推断它们。请注意，通常不支持在同一页面上嵌入多个 SvelteKit 应用，并在其中使用客户端 SvelteKit 功能（例如，将历史状态推送到单个实例）。

## env

环境变量配置

`` // @noErrors `没有错误 dir?: 字符串;` ``

*   默认`“.”`

搜索 `.env` 文件的目录。

```ts
// @noErrors
publicPrefix?: string;
```

*   默认`"PUBLIC_"`

前缀表示环境变量可以安全地暴露给客户端代码。请参阅 [`$env/static/public`](/docs/kit/$env-static-public) 和 [`$env/dynamic/public`](/docs/kit/$env-dynamic-public)。请注意，如果您使用 Vite 的环境变量处理，则必须单独设置 Vite 的 [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix)，尽管通常不需要使用该功能。

```ts
// @noErrors
privatePrefix?: string;
```

*   默认`""`
*   自 v1.21.0 起可用

前缀表示环境变量不安全，不能暴露给客户端代码。既不匹配公共前缀也不匹配私有前缀的环境变量将被完全丢弃。请参阅[`$env/static/private`](/docs/kit/$env-static-private)和[`$env/dynamic/private`](/docs/kit/$env-dynamic-private)。

## 
文件

在哪里可以找到项目中的各种文件。

```ts
// @noErrors
assets?: string;
```

*   默认`"静态"`

一个存放静态文件的地方，这些文件应具有稳定的 URL 且不经过处理，例如 `favicon.ico` 或 `manifest.json`

`` // @noErrors `没有错误 hooks?: {/*…*/}` ``

```ts
// @noErrors
client?: string;
```

*   默认`"src/hooks.client"`

您的客户端[钩子](/docs/kit/hooks)的位置。

```ts
// @noErrors
server?: string;
```

*   默认`"src/hooks.server"`

您的服务器位置 [钩子](/docs/kit/hooks)。

```ts
// @noErrors
universal?: string;
```

*   默认`"src/钩子"`
*   自 v2.3.0 起可用

您的通用[钩子](/docs/kit/hooks)的位置。

`` // @noErrors `没有错误 lib?: 字符串;` ``

*   默认`"src/lib"`

您的应用程序的内部库，在整个代码库中可通过`$lib`访问

```ts
// @noErrors
params?: string;
```

*   默认`"src/params"`

一个包含[参数匹配器](/docs/kit/advanced-routing#Matching)的目录

```ts
// @noErrors
routes?: string;
```

*   默认`"src/路由"`

文件定义您的应用程序结构（见[路由](/docs/kit/routing)）

```ts
// @noErrors
serviceWorker?: string;
```

*   默认`"src/service-worker"`

服务工作者入口点的位置（见[服务工作者](/docs/kit/service-workers)）

```ts
// @noErrors
appTemplate?: string;
```

*   默认`"src/app.html"`

模板的位置，用于 HTML 响应

```ts
// @noErrors
errorTemplate?: string;
```

*   默认`"src/error.html"`

模板的回退错误响应位置

## 
行内样式阈值

*   默认`0`

行内 CSS 位于 HTML 头部`<style>`块内。此选项是一个数字，指定 CSS 文件在 UTF-16 代码单元中的最大长度，如[String.length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length)属性所述，以行内形式存在。所有小于此值的页面所需的 CSS 文件都将合并并内联到`<style>`块中。

> \[注意\] 这会导致初始请求更少，并可以提高您的[首次内容绘制](https://web.dev/first-contentful-paint)得分。然而，它会产生更大的 HTML 输出，并降低浏览器缓存的效率。请谨慎使用。

## 
模块扩展

*   默认`[".js", ".ts"]`

文件扩展名数组，SvelteKit 将其视为模块。与 `config.extensions` 或 `config.kit.moduleExtensions` 不匹配的扩展名文件将被路由器忽略。

## 
输出目录

*   默认`“.svelte-kit”`

目录是 SvelteKit 在`dev`和`build`期间写入文件的目录。您应该将此目录排除在版本控制之外。

## 
输出

与构建输出格式相关的选项

```ts
// @noErrors
preloadStrategy?: 'modulepreload' | 'preload-js' | 'preload-mjs';
```

*   默认`"模块预加载"`
*   自 v1.8.4 起可用

SvelteKit 将预加载初始页面所需的 JavaScript 模块，以避免出现 'waterfalls' 导入，从而实现更快的应用程序启动。这里有三种策略，各有不同的权衡。

*   `模块预加载` - 使用 `<link rel="modulepreload">`。在基于 Chromium 的浏览器、Firefox 115+ 和 Safari 17+ 中效果最佳。在较旧浏览器中被忽略。
*   `preload-js` - 使用 `<link rel="preload">`。防止 Chromium 和 Safari 中的瀑布效应，但 Chromium 会解析每个模块两次（一次作为脚本，一次作为模块）。在 Firefox 中导致模块被请求两次。如果您想最大限度地提高 iOS 设备用户的性能，而以 Chromium 用户性能的轻微下降为代价，这是一个好的设置。
*   `preload-mjs` - 使用 `<link rel="preload">` 但带有 `.mjs` 扩展名，这可以防止在 Chromium 中重复解析。一些静态 Web 服务器可能会因为 `Content-Type: application/javascript` 头部而无法提供 .mjs 文件，这会导致您的应用程序崩溃。如果这不适合您，这是为最大数量的用户提供最佳性能的选项，直到 `modulepreload` 得到更广泛的支持。

```ts
// @noErrors
bundleStrategy?: 'split' | 'single' | 'inline';
```

*   默认`'split'`
*   自 v2.13.0 起可用

捆绑策略选项影响您的应用程序的 JavaScript 和 CSS 文件加载方式。

*   如果 `'split'`，则将应用拆分为多个.js/.css 文件，以便在用户在应用中导航时按需加载。这是默认设置，适用于大多数场景。
*   如果 `'single'`，则仅创建一个包含整个应用代码的 .js 包和一个 .css 文件。
*   如果 `'inline'`，则将整个应用的所有 JavaScript 和 CSS 内联到 HTML 中。结果无需服务器即可使用（即您可以直接在浏览器中打开文件）。

当使用`'split'`时，您还可以通过在您的 Vite 配置的[`build.rollupOptions`](https://vite.dev/config/build-options.html#build-rollupoptions)中设置 [`output.experimentalMinChunkSize`](https://rollupjs.org/configuration-options/#output-experimentalminchunksize) 和[`output.manualChunks`](https://rollupjs.org/configuration-options/#output-manualchunks)来调整捆绑行为。

如果您想内联您的资源，您需要将 Vite 的 [`build.assetsInlineLimit`](https://vite.dev/config/build-options.html#build-assetsinlinelimit) 选项设置为适当的大小，然后通过 Vite 导入您的资源。

```js
// @errors: 7031
/// file: vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [sveltekit()],
	build: {
		// inline all imported assets
		assetsInlineLimit: Infinity
	}
});
```

```svelte
/// file: src/routes/+layout.svelte
<script>
	// import the asset through Vite
	import favicon from './favicon.png';
</script>

<svelte:head>
	<!-- this asset will be inlined as a base64 URL -->
	<link rel="icon" href={favicon} />
</svelte:head>
```

## 
路径

```ts
// @noErrors
assets?: '' | `http://${string}` | `https://${string}`;
```

*   默认`""`

绝对路径，您的应用程序文件从中提供的服务路径。如果您的文件是从某种存储桶中提供服务的，这很有用。

```ts
// @noErrors
base?: '' | `/${string}`;
```

*   默认`""`

根相对路径必须以`/`开头，但不能以`/`结尾（例如：`/base-path`），除非它是空字符串。这指定了您的应用程序从哪里提供服务，并允许应用程序存在于非根路径上。请注意，您需要将所有根相对链接都添加基本值作为前缀，否则它们将指向域的根，而不是您的`基本`（这就是浏览器的工作方式）。您可以使用从`$app/paths`中的`基本`[：](/docs/kit/$app-paths#base)进行此操作： `<a href="{base}/your-page">Link</a>` 。如果您经常编写此内容，将其提取为可重用组件可能是有意义的。

```ts
// @noErrors
relative?: boolean;
```

*   默认`真`
*   自 v1.9.0 起可用

是否使用相对资源路径。

如果 `true`，则从 `$app/paths` 导入的 `base` 和 `assets` 在服务器端渲染期间将被替换为相对资产路径，从而生成更易于携带的 HTML。如果 `false`，则 `%sveltekit.assets%` 和对构建实体的引用将始终是根相关路径，除非 `paths.assets` 是外部 URL。

[单页应用程序](/docs/kit/single-page-apps)回退页面将始终使用绝对路径，无论此设置如何。

如果您的应用使用了`<base>`元素，您应该将其设置为`false`，否则资产 URL 将不正确地相对于`<base>` URL 解析，而不是当前页面。

在 1.0 版本中，`undefined`是一个有效的值，默认设置为该值。在这种情况下，如果`paths.assets`不是外部的，SvelteKit 会将`%sveltekit.assets%`替换为相对路径，并使用相对路径来引用构建工件，但从`$app/paths`导入的`base`和`assets`将按照您的配置指定。

## 
预渲染

查看[预渲染](/docs/kit/page-options#prerender)。

```ts
// @noErrors
concurrency?: number;
```

*   默认`1`

一次可以预渲染多少页。JavaScript 是单线程的，但在预渲染性能受网络限制的情况下（例如从远程 CMS 加载内容），这可以通过在等待网络响应时处理其他任务来加快速度。

```ts
// @noErrors
crawl?: boolean;
```

*   默认`真`

是否 SvelteKit 应通过跟随从`entries`的链接来查找需要预渲染的页面。

```ts
// @noErrors
entries?: Array<'*' | `/${string}`>;
```

*   默认`["*"]`

一個待預渲染的頁面數組，或從此開始爬取（如果 `crawl: true`）。`*` 字符串包括所有不包含必需的 `[參數]` 且選項參數為空的路由（因為 SvelteKit 不清楚任何參數應該有何值）。

```ts
// @noErrors
handleHttpError?: PrerenderHttpErrorHandlerValue;
```

*   默认`"失败"`
*   自 v1.15.7 起可用

如何应对在预渲染应用时遇到的 HTTP 错误。

*   `失败` — 构建失败
*   `忽略` - 静默忽略失败并继续
*   `警告` — 继续执行，但打印警告
*   `(详细信息) => void` — 一个自定义错误处理器，它接受一个具有`状态`、`路径`、`来源`、`引用类型`和`消息`属性的`详细信息`对象。如果您从这个函数中`抛出异常`，构建将失败

```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		prerender: {
			handleHttpError: ({ path, referrer, message }) => {
				// ignore deliberate link to shiny 404 page
				if (path === '/not-found' && referrer === '/blog/how-we-built-our-404-page') {
					return;
				}

				// otherwise fail the build
				throw new Error(message);
			}
		}
	}
};
```

```ts
// @noErrors
handleMissingId?: PrerenderMissingIdHandlerValue;
```

*   默认`"失败"`
*   自 v1.15.7 起可用

如何应对从一个预渲染页面到另一个页面时，哈希链接与目标页面上的 `id` 不对应的情况。

*   `失败` — 构建失败
*   `忽略` - 静默忽略失败并继续
*   `警告` — 继续执行，但打印警告
*   `(详细信息) => void` — 一个自定义错误处理器，它接受一个具有`路径`、`id`、`引用者`和`消息`属性的`详细信息`对象。如果您从这个函数中`抛出`，构建将失败

```ts
// @noErrors
handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue;
```

*   默认`"失败"`
*   自 v1.16.0 起可用

如何应对由`entries`导出生成的条目与其生成的路由不匹配的情况。

*   `失败` — 构建失败
*   `忽略` - 静默忽略失败并继续
*   `警告` — 继续执行，但打印警告
*   `(详细信息) => void` — 一个自定义错误处理器，它接受一个具有 `generatedFromId`、`entry`、`matchedId` 和 `message` 属性的 `details` 对象。如果您从这个函数中 `throw`，构建将失败

```ts
// @noErrors
origin?: string;
```

*   默认`"http://sveltekit-prerender"`

The value of `url.origin` during prerendering; useful if it is included in rendered content.

## 
路由器

```ts
// @noErrors
type?: 'pathname' | 'hash';
```

*   默认`"路径名"`
*   自 v2.14.0 起可用

使用哪种客户端路由器。

*   `‘pathname’`是默认值，表示当前 URL 的路径名决定路由
*   `‘hash’` 表示路由由 `location.hash` 决定。在这种情况下，SSR 和预渲染被禁用。只有在 `pathname` 不可选时才推荐这样做，例如，因为你无法控制部署应用程序的 web 服务器。它带来了一些注意事项：你不能使用服务器端渲染（或者确实任何服务器逻辑），并且你必须确保你的应用程序中的所有链接都以 #/ 开头，否则它们将无法工作。除此之外，一切工作方式都与正常的 SvelteKit 应用程序完全相同。

```ts
// @noErrors
resolution?: 'client' | 'server';
```

*   默认`"客户端"`
*   自 v2.17.0 起可用

如何确定在导航到新页面时加载哪条路由。

默认情况下，SvelteKit 将为浏览器提供路由清单。在导航时，此清单（以及如果存在，则使用`reroute`钩子）用于确定要加载哪些组件以及要运行哪些`load`函数。因为所有操作都在客户端进行，所以这个决定可以立即做出。缺点是必须在第一次导航之前加载和解析清单，如果您的应用程序包含许多路由，这可能会产生影响。

或者，SvelteKit 可以在服务器上确定路由。这意味着对于每个导航到尚未访问的路径，服务器将被要求确定路由。这有几个优点：

*   客户端无需预先加载路由清单，这可以导致页面初始加载更快
*   路由列表对公众隐藏
*   服务器有机会拦截每次导航（例如通过中间件），从而实现（例如）对 SvelteKit 不可见的 A/B 测试

缺点是对于未访问的路径，解析将稍微花费更长的时间（尽管这可以通过[预加载](/docs/kit/link-options#data-sveltekit-preload-data)来缓解）。

> \[注意\] 当使用服务器端路由解析和预渲染时，解析将与路由本身一起预渲染。

## 
服务工作者

```ts
// @noErrors
register?: boolean;
```

*   默认`真`

是否自动注册存在的服务工作者。

```ts
// @noErrors
files?(filepath: string): boolean;
```

*   默认 `(filename) => !/\.DS_Store/.test(filename)`

确定你的 `static` 目录中哪些文件将在 `$service-worker.files` 中可用。

## typescript

```ts
// @noErrors
config?: (config: Record<string, any>) => Record<string, any> | void;
```

*   默认`(配置) => 配置`
*   自 v1.3.0 起可用

一个允许您编辑生成的`tsconfig.json`的函数。您可以修改配置（推荐）或返回一个新的配置。这在扩展 monorepo 根目录中的共享`tsconfig.json`时非常有用。

## 
版本

客户端导航可能会出现 bug，如果您在用户使用应用时部署新版本，如果新页面的代码已经加载，它可能包含过时内容；如果没有加载，应用的路线清单可能指向一个不再存在的 JavaScript 文件。SvelteKit 通过版本管理帮助您解决这个问题。如果 SvelteKit 在加载页面时遇到错误并检测到已部署新版本（使用此处指定的`name`，默认为构建的时间戳），它将回退到传统的全页导航。并非所有导航都会导致错误，例如，如果下一页的 JavaScript 已经加载。如果您仍然想在这些情况下强制全页导航，请使用设置`pollInterval`然后使用`beforeNavigate`等技术。

```html
/// file: +layout.svelte
<script>
	import { beforeNavigate } from '$app/navigation';
	import { updated } from '$app/state';

	beforeNavigate(({ willUnload, to }) => {
		if (updated.current && !willUnload && to?.url) {
			location.href = to.url.href;
		}
	});
</script>
```

如果您将`pollInterval`设置为非零值，SvelteKit 将在后台轮询新版本，并在检测到新版本时将`[updated.current](/docs/kit/$app-state#updated)``true`的值设置为。

`` // @noErrors `没有错误 名称?: 字符串;` ``

当前应用版本字符串。如果指定，则必须是确定的（例如，提交引用而不是 `Math.random()` 或 `Date.now().toString()`），否则默认为构建的时间戳。

例如，要使用当前的提交哈希，您可以这样做：使用 `git rev-parse HEAD`：

```js
// @errors: 7031
/// file: svelte.config.js
import * as child_process from 'node:child_process';

export default {
	kit: {
		version: {
			name: child_process.execSync('git rev-parse HEAD').toString().trim()
		}
	}
};
```

```ts
// @noErrors
pollInterval?: number;
```

*   默认`0`

毫秒级的轮询版本更改的间隔。如果这是 `0`，则不进行轮询。