配置
项目的配置位于项目根目录下的 svelte.config.js
文件中。除了 SvelteKit 之外,此配置对象还用于与 Svelte 集成的其他工具,例如编辑器扩展。
import const adapter: () => import("@sveltejs/kit").Adapter
adapter from '@sveltejs/adapter-auto';
/** @type {import('@sveltejs/kit').Config} */
const const config: Config
config = {
Config.kit?: KitConfig | undefined
SvelteKit options
kit: {
KitConfig.adapter?: Adapter | undefined
Your adapter is run when executing vite build
. It determines how the output is converted for different platforms.
adapter: function adapter(): import("@sveltejs/kit").Adapter
adapter()
}
};
export default const config: Config
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,并且可以具有以下属性
适配器
- 默认
undefined
执行 vite build
时将运行您的 适配器。它决定如何将输出转换为不同平台。
别名
- 默认
{}
包含一个或多个用于替换 import
语句中值的别名的对象。这些别名会自动传递给 Vite 和 TypeScript。
/** @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: {
// 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
,则将有两个 app 目录——${paths.assets}/${appDir}
和 ${paths.base}/${appDir}
。
csp
内容安全策略 配置。CSP 通过限制可以从哪些位置加载资源来帮助保护用户免受跨站点脚本 (XSS) 攻击。例如,如下配置...
/** @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']
},
// must be specified with either the `report-uri` or `report-to` directives, or both
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
钩子 来创建自己的 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
是否检查传入的 origin
标头以获取 POST
、PUT
、PATCH
或 DELETE
表单提交,并验证它是否与服务器的来源匹配。
要允许人们以 application/x-www-form-urlencoded
、multipart/form-data
或 text/plain
的 Content-Type
从其他来源向您的应用发出 POST
、PUT
、PATCH
或 DELETE
请求,您需要禁用此选项。小心!
嵌入
- 默认
false
该应用是否嵌入在一个更大的应用中。如果为 true
,SvelteKit 将在 %sveltekit.body%
的父级而不是 window
上添加其与导航等相关的事件侦听器,并将从服务器传递 params
而不是从 location.pathname
推断它们。请注意,通常不支持在同一页面上嵌入多个 SvelteKit 应用并在其中使用客户端 SvelteKit 功能(例如,推送到历史状态假设单个实例)。
环境
环境变量配置
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
。
文件
在您的项目中查找各种文件的位置。
assets?: string;
- 默认
"static"
放置静态文件的位置,这些文件应具有稳定的 URL 并且不进行任何处理,例如 favicon.ico
或 manifest.json
hooks?: {…}
lib?: string;
- 默认
"src/lib"
应用的内部库,可在整个代码库中作为 $lib
访问
params?: string;
- 默认
"src/params"
包含 参数匹配器 的目录
routes?: string;
- 默认
"src/routes"
定义应用结构的文件(请参阅 路由)
serviceWorker?: string;
- 默认
"src/service-worker"
服务工作者的入口点位置(请参阅 服务工作者)
appTemplate?: string;
- 默认
"src/app.html"
HTML 响应模板的位置
errorTemplate?: string;
- 默认
"src/error.html"
回退错误响应模板的位置
inlineStyleThreshold
- 默认
0
在 HTML 头部的 <style>
块中内联 CSS。此选项是一个数字,指定要内联的 CSS 文件在 UTF-16 代码单元中的最大长度,如 String.length 属性指定的那样。页面所需的所有 CSS 文件,并且小于此值,都会合并并内联到 <style>
块中。
这会导致初始请求减少,并可以提高您的 首次内容绘制 分数。但是,它会生成更大的 HTML 输出并降低浏览器缓存的有效性。谨慎使用。
moduleExtensions
- 默认
[".js", ".ts"]
SvelteKit 将视为模块的文件扩展名的数组。扩展名既不匹配 config.extensions
也不匹配 config.kit.moduleExtensions
的文件将被路由器忽略。
outDir
- 默认
".svelte-kit"
SvelteKit 在 dev
和 build
期间将文件写入到的目录。您应该将此目录排除在版本控制之外。
输出
与构建输出格式相关的选项
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 服务器无法使用Content-Type: application/javascript
标头提供 .mjs 文件,这会导致您的应用程序崩溃。如果这并不适用于您,那么在modulepreload
获得更广泛的支持之前,此选项将为大多数用户提供最佳性能。
paths
assets?: '' | `http://${string}` | `https://${string}`;
- 默认
""
应用程序文件所在的绝对路径。如果您从某种存储桶中提供文件,这将很有用。
base?: '' | `/${string}`;
- 默认
""
必须以 /
开头但不能以 /
结尾的根相对路径(例如 /base-path
),除非它是空字符串。这指定了应用程序的提供位置,并允许应用程序位于非根路径上。请注意,您需要在所有根相对链接前加上基本值,否则它们将指向域的根目录,而不是您的 base
(这是浏览器的运作方式)。您可以使用 $app/paths
中的 base
来实现:<a href="{base}/your-page">Link</a>
。如果您发现自己经常编写此代码,则将其提取到可重用组件中可能更有意义。
relative?: boolean;
- 默认
true
- 自版本 v1.9.0 起可用
是否使用相对资产路径。
如果 true
,则在服务器端渲染期间,从 $app/paths
导入的 base
和 assets
将被替换为相对资产路径,从而产生更便携的 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
可以同时预渲染多少个页面。JS 是单线程的,但在预渲染性能受网络限制的情况下(例如从远程 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 }) => {
// ignore deliberate link to shiny 404 page
if (path: any
path === '/not-found' && referrer: any
referrer === '/blog/how-we-built-our-404-page') {
return;
}
// otherwise fail the build
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
的值;如果它包含在渲染内容中,则很有用。
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/stores';
beforeNavigate(({ willUnload, to }) => {
if ($updated && !willUnload && to?.url) {
location.href = to.url.href;
}
});
</script>
如果您将 pollInterval
设置为非零值,SvelteKit 将在后台轮询新版本,并在检测到新版本时将 updated
存储的值设置为 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
,则不进行轮询。