配置
您的项目配置位于项目根目录下的 svelte.config.js
文件中。除了 SvelteKit 外,此配置对象还被其他与 Svelte 集成的工具(如编辑器扩展)使用。
/// 文件: svelte.config.js
// @文件名: ambient.d.ts
declare module '@sveltejs/adapter-auto' {
const const plugin: () => import("@sveltejs/kit").Adapter
plugin: () => import('@sveltejs/kit').Adapter;
export default const plugin: () => import("@sveltejs/kit").Adapter
plugin;
}
// @文件名: index.js
//切割
import import adapter
adapter from '@sveltejs/adapter-auto';
/** @type {import('@sveltejs/kit').Config} */
const const config: {
kit: {
adapter: any;
};
}
config = {
kit: {
adapter: any;
}
kit: {
adapter: any
adapter: import adapter
adapter()
}
};
export default const config: {
kit: {
adapter: any;
};
}
config;
配置
interface Config {…}
compilerOptions?: CompileOptions;
- 默认
{}
传递给 svelte.compile
的选项。
extensions?: string[];
- 默认
[".svelte"]
应视为 Svelte 文件的文件扩展名列表。
kit?: KitConfig;
SvelteKit 配置选项
preprocess?: any;
预处理选项(如果有)。预处理也可以通过 Vite 的预处理功能实现。
vitePlugin?: PluginOptions;
vite-plugin-svelte
插件选项。
[key: string]: any;
任何需要 Svelte 集成工具的额外选项。
KitConfig
kit
属性用于配置 SvelteKit,并可以具有以下属性:
adapter
- 默认
undefined
当执行 vite build
时运行您的 适配器。它决定如何将输出转换为适应不同平台的格式。
alias
- 默认
{}
一个包含零个或多个别名的对象,用于替换 import
语句中的值。这些别名会自动传递给 Vite 和 TypeScript。
/// 文件: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const const config: {
kit: {
alias: {
'my-file': string;
'my-directory': string;
'my-directory/*': string;
};
};
}
config = {
kit: {
alias: {
'my-file': string;
'my-directory': string;
'my-directory/*': string;
};
}
kit: {
alias: {
'my-file': string;
'my-directory': string;
'my-directory/*': string;
}
alias: {
// 这将匹配一个文件
'my-file': 'path/to/my-file.js',
// 这将匹配一个目录及其内容
// (`my-directory/x` 解析到 `path/to/my-directory/x`)
'my-directory': 'path/to/my-directory',
// 以 /* 结尾的别名将只匹配目录中的内容,而不是目录本身
'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
内容安全策略 (Content Security Policy) 配置。CSP 有助于保护您的用户免受跨站脚本 (XSS) 攻击,通过限制资源加载来源。例如,类似这样的配置……
/// 文件: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const const config: {
kit: {
csp: {
directives: {
'script-src': string[];
};
reportOnly: {
'script-src': string[];
'report-uri': string[];
};
};
};
}
config = {
kit: {
csp: {
directives: {
'script-src': string[];
};
reportOnly: {
'script-src': string[];
'report-uri': string[];
};
};
}
kit: {
csp: {
directives: {
'script-src': string[];
};
reportOnly: {
'script-src': string[];
'report-uri': string[];
};
}csp: {
directives: {
'script-src': string[];
}directives: {
'script-src': ['self']
},
// 必须指定 `report-uri` 或 `report-to` 指令,或同时指定二者
reportOnly: {
'script-src': string[];
'report-uri': string[];
}reportOnly: {
'script-src': ['self'],
'report-uri': ['/']
}
}
}
};
export default const config: {
kit: {
csp: {
directives: {
'script-src': string[];
};
reportOnly: {
'script-src': string[];
'report-uri': string[];
};
};
};
}config;……将阻止从外部网站加载脚本。SvelteKit 将为它生成的任何内联样式和脚本添加 nonce 或哈希(取决于 mode
)。
要为手动包含在 src/app.html
中的脚本和链接添加 nonce,可以使用占位符 %sveltekit.nonce%
(例如 <script nonce="%sveltekit.nonce%">
)。
当页面被预渲染时,CSP 标头将通过 <meta http-equiv>
标签添加(注意,在此情况下,将忽略 frame-ancestors
、report-uri
和 sandbox
指令)。
[!注意] 当
mode
设置为'auto'
时,SvelteKit 将对动态渲染页面使用 nonce,对预渲染页面使用哈希。用 nonce 处理预渲染页面是不安全的,因此被禁止。
[!注意] 大多数 Svelte 转场 的工作方式是创建一个内联
<style>
元素。如果您在应用中使用这些功能,必须要么不指定style-src
指令,要么添加unsafe-inline
。
如果需要更动态的配置,可以使用 handle
hook 自行构建 CSP。
mode?: 'hash' | 'nonce' | 'auto';
指定是否使用哈希或 nonce 来限制 <script>
和 <style>
元素。'auto'
会在预渲染页面中使用哈希,而在动态渲染页面中使用 nonce。
directives?: CspDirectives;
将添加到 Content-Security-Policy
标头的指令。
reportOnly?: CspDirectives;
将添加到 Content-Security-Policy-Report-Only
标头的指令。
csrf
防止 跨站请求伪造(CSRF) 的攻击。
checkOrigin?: boolean;
- 默认
true
是否在 POST
、PUT
、PATCH
或 DELETE
表单提交中检查传入的 origin
标头并验证是否与服务端的 origin 匹配。
要允许人们从其他来源向您的应用发送 POST
、PUT
、PATCH
或 DELETE
请求,其 Content-Type
为 application/x-www-form-urlencoded
、multipart/form-data
或 text/plain
,需要禁用此选项。请谨慎操作!
嵌入式应用
- 默认值
false
应用是否嵌入在一个更大的应用中。如果设置为 true
,SvelteKit 将在 %sveltekit.body%
的父级上而不是 window
上添加与导航相关的事件监听器,并从服务端传递 params
,而不是从 location.pathname
推导。
请注意:通常不支持在同一页面中嵌入多个 SvelteKit 应用并在它们之间使用客户端 SvelteKit 功能(例如推送历史状态等操作假设只有一个实例)。
环境变量配置 (env)
环境变量配置
dir?: string;
- 默认值
"."
用于搜索 .env
文件的目录。
publicPrefix?: string;
- 默认值
"PUBLIC_"
一个前缀,用于指示环境变量可以安全地暴露给客户端代码。参考 $env/static/public
和 $env/dynamic/public
。如果您使用的是 Vite 的环境变量处理,Vite 的 envPrefix
必须单独设置,但通常不需要使用该功能。
privatePrefix?: string;
- 默认值
""
- 自版本 v1.21.0 开始可用
一个前缀,用于指示环境变量不能暴露给客户端代码。不符合公共或私有前缀的环境变量将完全被丢弃。参考 $env/static/private
和 $env/dynamic/private
。
文件路径配置 (files)
定义项目中各种文件的位置。
assets?: string;
- 默认值
"static"
一个用于存放静态文件的位置,这些文件应具有稳定的 URL 并且不进行任何处理,例如 favicon.ico
或 manifest.json
。
hooks?: {…}
lib?: string;
- 默认值
"src/lib"
应用的内部库位置,可在代码库中通过 $lib
访问。
params?: string;
- 默认值
"src/params"
包含 参数匹配器 的目录。
routes?: string;
- 默认值
"src/routes"
定义应用结构的文件位置 (参考 Routing)。
serviceWorker?: string;
- 默认值
"src/service-worker"
server workers 入口点的位置 (参考 server workers )。
appTemplate?: string;
- 默认值
"src/app.html"
HTML 响应模板的位置。
errorTemplate?: string;
- 默认值
"src/error.html"
回退错误响应的模板位置。
inlineStyleThreshold
- 默认值
0
将 CSS 内联到 HTML 头部的 <style>
块中。此选项是一个数字,指定 UTF-16 代码单元(由 String.length 属性定义)中 CSS 文件的最大长度。页面需要的所有小于此值的 CSS 文件都会被合并并内联到 <style>
块中。
这会减少初始请求并可以提高 First Contentful Paint 指标。但这会生成更大的 HTML 输出,并降低浏览器缓存的效果。请谨慎使用。
moduleExtensions
- 默认值
[".js", ".ts"]
一个文件扩展名数组,SvelteKit 会将其视为模块。不匹配 config.extensions
或 config.kit.moduleExtensions
的扩展名文件将被路由器忽略。
outDir
- 默认值
".svelte-kit"
SvelteKit 在 dev
和 build
阶段将文件写入的目录。您应该将此目录排除在版本控制之外。
output
与构建输出格式相关的选项。
preloadStrategy?: 'modulepreload' | 'preload-js' | 'preload-mjs';
- 默认值
"modulepreload"
- 可用版本 v1.8.4
SvelteKit 将预加载初始页面所需的 JavaScript 模块,以避免“导入瀑布”,从而加快应用程序启动速度。以下是三种策略及其权衡:
modulepreload
- 使用<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 服务端可能无法为 .mjs 文件设置Content-Type: application/javascript
响应头,可能导致应用程序中断。如果这些问题不适用于您的情况,这是为大多数用户提供最佳性能的选项,直到modulepreload
被更广泛地支持。
bundleStrategy?: 'split' | 'single' | 'inline';
- 默认值
'split'
- 可用版本 v2.13.0
- 如果选择
'split'
,应用程序会被拆分为多个 .js/.css 文件,并根据用户在应用中导航时延迟加载。这是默认设置并建议用于大多数场景。 - 如果选择
'single'
,会创建一个包含整个应用代码的 .js 文件和一个 .css 文件。 - 如果选择
'inline'
,会将整个应用的 JavaScript 和 CSS 内联到 HTML 中。结果是可以在没有服务端的情况下使用(即您可以直接在浏览器中打开文件)。
当使用 'split'
时,您还可以通过设置 Vite 配置中的 build.rollupOptions
内的 output.experimentalMinChunkSize
和 output.manualChunks
来调整捆绑行为。
paths
assets?: '' | `http://${string}` | `https://${string}`;
- 默认值
""
一个表示应用文件提供路径的绝对路径。这在您的文件从某种存储桶提供时很有用。
base?: '' | `/${string}`;
- 默认值
""
一个相对根路径,必须以 /
开头但不能以 /
结尾(例如 /base-path
),除非它是空字符串。这指定了应用的服务路径,并允许应用运行在非根路径中。需要注意,您必须为所有的相对根链接添加 base 值前缀,否则它们将指向域的根路径,而非您的 base
(浏览器的工作方式)。您可以使用 base
from $app/paths
来处理:<a href="{base}/your-page">Link</a>
。如果您需要经常这样写,或许可以将其抽象成一个可重复使用的组件。
relative?: boolean;
- 默认值
true
- 可用版本 v1.9.0
是否使用相对资源路径。
如果为 true
,在服务端渲染时,base
和 assets
(从 $app/paths
导入)会被替换为相对资源路径,生成更具可移植性的 HTML。如果为 false
,%sveltekit.assets%
和对构建产物的引用将始终为根相对路径,除非 paths.assets
是一个外部 URL。
单页面应用 的回退页面将始终使用绝对路径,而不考虑此设置。
如果应用使用 <base>
元素,您应将此设置为 false
,否则资源 URL 将错误地按 <base>
的 URL 而非当前页面进行解析。
在 1.0 版本中,undefined
是一个有效的值(默认值)。在这种情况下,如果 paths.assets
不是外部资源,SvelteKit 会用相对路径替换 %sveltekit.assets%
并引用构建产物,但从 $app/paths
导入的 base
和 assets
会按配置指定。
预渲染(prerender)
详见 预渲染。
concurrency?: number;
- 默认
1
可以同时预渲染多少个页面。尽管 JavaScript 是单线程的,但如果预渲染性能受网络限制(例如从远程 CMS 加载内容),在等待网络响应时处理其他任务可以提高速度。
crawl?: boolean;
- 默认
true
SvelteKit 是否通过从 entries
中的链接来查找预渲染的页面。
entries?: var Array: ArrayConstructor
Array<'*' | `/${string}`>;
- 默认
["*"]
一个包含待预渲染页面,或用于开始爬取的数组(如果 crawl: true
)。字符串 *
包括所有不含必填 [parameters]
的路由,可选参数为空(因为 SvelteKit 无法知道参数的值应该是什么)。
handleHttpError?: PrerenderHttpErrorHandlerValue;
- 默认
"fail"
- 自 v1.15.7 可用
如何处理预渲染应用时遇到的 HTTP 错误。
'fail'
— 构建失败'ignore'
- 安静地忽略错误并继续'warn'
— 继续但打印警告(details) => void
— 一个使用带有status
、path
、referrer
、referenceType
和message
属性的details
对象的自定义错误处理器。如果在该函数中throw
,构建将失败
/** @type {import('@sveltejs/kit').Config} */
const const config: {
kit: {
prerender: {
handleHttpError: ({ path, referrer, message }: {
path: any;
referrer: any;
message: any;
}) => void;
};
};
}
config = {
kit: {
prerender: {
handleHttpError: ({ path, referrer, message }: {
path: any;
referrer: any;
message: any;
}) => void;
};
}
kit: {
prerender: {
handleHttpError: ({ path, referrer, message }: {
path: any;
referrer: any;
message: any;
}) => void;
}
prerender: {
handleHttpError: ({ path, referrer, message }: {
path: any;
referrer: any;
message: any;
}) => void
handleHttpError: ({ path: any
path, referrer: any
referrer, message: any
message }) => {
// 忽略指向有设计感的404页面的链接
if (path: any
path === '/not-found' && referrer: any
referrer === '/blog/how-we-built-our-404-page') {
return;
}
// 否则,构建失败
throw new var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error(message: any
message);
}
}
}
};handleMissingId?: PrerenderMissingIdHandlerValue;
- 默认
"fail"
- 自 v1.15.7 可用
当一个预渲染页面的哈希链接没有对应的目标页面中的 id
时,该如何响应。
'fail'
— 构建失败'ignore'
- 安静地忽略错误并继续'warn'
— 继续但打印警告(details) => void
— 一个使用带有path
、id
、referrers
和message
属性的details
对象的自定义错误处理器。如果在该函数中throw
,构建将失败
handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue;
- 默认
"fail"
- 自 v1.16.0 可用
当由 entries
导出的条目与生成它的路由不匹配时,该如何响应。
'fail'
— 构建失败'ignore'
- 安静地忽略错误并继续'warn'
— 继续但打印警告(details) => void
— 一个使用带有generatedFromId
、entry
、matchedId
和message
属性的details
对象的自定义错误处理器。如果在该函数中throw
,构建将失败
var origin: string
origin?: string;
- 默认
"http://sveltekit-prerender"
在预渲染时,url.origin
的值;如果它被包含在渲染的内容中,则很有用。
路由器(router)
type?: 'pathname' | 'hash';
- 默认
"pathname"
- 自 v2.14.0 可用
使用哪种类型的客户端路由器。
'pathname'
是默认选项,意味着当前 URL 的路径名决定了路由。'hash'
表示路由由location.hash
确定。在这种情况下,SSR 和预渲染被禁用。仅当pathname
无法作为选项时推荐使用,例如由于您无法控制应用程序部署的 Web 服务端。 这种方式有一些注意事项:您无法使用服务端渲染(或任何服务端逻辑),并且需要确保应用程序中的链接都以 /#/ 开头,否则它们将无法工作。除此之外,其他功能与普通 SvelteKit 应用程序完全相同。
服务工作器(serviceWorker)
register?: boolean;
- 默认
true
是否自动注册服务工作器(如果有)。
files?(filepath: string
filepath: string): boolean;
- 默认
(filename) => !/\.DS_Store/.test(filename)
决定您的 static
目录中的哪些文件可以在 $service-worker.files
中使用。
TypeScript
config?: (config: Record<string, any>
config: type Record<K extends keyof any, T> = { [P in K]: T; }
Construct a type with a set of properties K of type T
Record<string, any>) => Record<string, any> | void;
- 默认
(config) => config
- 自 v1.3.0 可用
一个允许您编辑生成的 tsconfig.json
的函数。您可以直接修改配置(推荐)或返回一个新的配置。
这在扩展单一工作区根目录中的共享 tsconfig.json
时很有用。
版本(version)
如果您在应用程序使用过程中部署新版本,客户端导航可能会有问题。如果新页面的代码已经加载,它可能包含过期内容;如果没有加载,应用程序的路由清单可能指向一个不再存在的 JavaScript 文件。
SvelteKit 可通过版本管理帮助您解决这个问题。
如果 SvelteKit 在加载页面时检测到错误,并且检测到部署了一个新版本(使用这里指定的 name
,默认为构建的时间戳),它将回退到传统的页面整体刷新。
但是,并非所有导航错误都会触发,例如下一个页面的 JavaScript 已加载的情况下。如果您仍希望强制页面整体刷新,可以使用如下方法设置 pollInterval
并结合使用 beforeNavigate
:
<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
的值设置为 true
。
const name: void
name?: string;
当前应用程序版本字符串。如果指定,必须是确定性的(例如提交引用,而不是 Math.random()
或 Date.now().toString()
),否则默认为构建的时间戳。
例如,要使用当前的提交哈希,您可以通过 git rev-parse HEAD
:
import * as module "node:child_process"
child_process from 'node:child_process';
export default {
kit: {
version: {
name: string;
};
}
kit: {
version: {
name: string;
}
version: {
name: string
name: module "node:child_process"
child_process.function execSync(command: string): Buffer (+3 overloads)
The child_process.execSync()
method is generally identical to
{@link
exec
}
with the exception that the method will not return
until the child process has fully closed. When a timeout has been encountered
and killSignal
is sent, the method won’t return until the process has
completely exited. If the child process intercepts and handles the SIGTERM
signal and doesn’t exit, the parent process will wait until the child process
has exited.
If the process times out or has a non-zero exit code, this method will throw.
The Error
object will contain the entire result from
{@link
spawnSync
}
.
Never pass unsanitized user input to this function. Any input containing shell
metacharacters may be used to trigger arbitrary command execution.
execSync('git rev-parse HEAD').Buffer.toString(encoding?: BufferEncoding, start?: number, end?: number): string
Decodes buf
to a string according to the specified character encoding inencoding
. start
and end
may be passed to decode only a subset of buf
.
If encoding
is 'utf8'
and a byte sequence in the input is not valid UTF-8,
then each invalid byte is replaced with the replacement character U+FFFD
.
The maximum length of a string instance (in UTF-16 code units) is available
as
{@link
constants.MAX_STRING_LENGTH
}
.
import { Buffer } from 'node:buffer';
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde
const buf2 = Buffer.from('tést');
console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té
toString().String.trim(): string
Removes the leading and trailing white space and line terminator characters from a string.
trim()
}
}
};
pollInterval?: number;
- 默认
0
轮询版本变化的时间间隔(单位:毫秒)。如果设置为 0
,则不会进行轮询。