Skip to main content

配置

您的项目配置位于项目根目录下的 svelte.config.js 文件中。除了 SvelteKit 外,此配置对象还被其他与 Svelte 集成的工具(如编辑器扩展)使用。

/// 文件: svelte.config.js
// @文件名: ambient.d.ts
declare module '@sveltejs/adapter-auto' {
	const const plugin: () => import("@sveltejs/kit").Adapterplugin: () => import('@sveltejs/kit').Adapter;
	export default const plugin: () => import("@sveltejs/kit").Adapterplugin;
}

// @文件名: index.js
//切割
import import adapteradapter from '@sveltejs/adapter-auto';

/** @type {import('@sveltejs/kit').Config} */
const 
const config: {
    kit: {
        adapter: any;
    };
}
@type{import('@sveltejs/kit').Config}
config
= {
kit: {
    adapter: any;
}
kit
: {
adapter: anyadapter: import adapteradapter() } }; export default
const config: {
    kit: {
        adapter: any;
    };
}
@type{import('@sveltejs/kit').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,并可以具有以下属性:

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;
        };
    };
}
@type{import('@sveltejs/kit').Config}
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.jsontsconfig.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[];
 };
        };
    };
}
@type{import('@sveltejs/kit').Config}
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[];
            };
        };
    };
}
@type{import('@sveltejs/kit').Config}
config
;

……将阻止从外部网站加载脚本。SvelteKit 将为它生成的任何内联样式和脚本添加 nonce 或哈希(取决于 mode)。

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

当页面被预渲染时,CSP 标头将通过 <meta http-equiv> 标签添加(注意,在此情况下,将忽略 frame-ancestorsreport-urisandbox 指令)。

[!注意] 当 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

是否在 POSTPUTPATCHDELETE 表单提交中检查传入的 origin 标头并验证是否与服务端的 origin 匹配。

要允许人们从其他来源向您的应用发送 POSTPUTPATCHDELETE 请求,其 Content-Typeapplication/x-www-form-urlencodedmultipart/form-datatext/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.icomanifest.json

hooks?: {}
client?: string;
  • 默认值 "src/hooks.client"

客户端 hooks 文件的位置。

server?: string;
  • 默认值 "src/hooks.server"

服务端 hooks 文件的位置。

universal?: string;
  • 默认值 "src/hooks"
  • 自版本 v2.3.0 开始可用

通用 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.extensionsconfig.kit.moduleExtensions 的扩展名文件将被路由器忽略。

outDir

  • 默认值 ".svelte-kit"

SvelteKit 在 devbuild 阶段将文件写入的目录。您应该将此目录排除在版本控制之外。

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.experimentalMinChunkSizeoutput.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,在服务端渲染时,baseassets(从 $app/paths 导入)会被替换为相对资源路径,生成更具可移植性的 HTML。如果为 false%sveltekit.assets% 和对构建产物的引用将始终为根相对路径,除非 paths.assets 是一个外部 URL。

单页面应用 的回退页面将始终使用绝对路径,而不考虑此设置。

如果应用使用 <base> 元素,您应将此设置为 false,否则资源 URL 将错误地按 <base> 的 URL 而非当前页面进行解析。

在 1.0 版本中,undefined 是一个有效的值(默认值)。在这种情况下,如果 paths.assets 不是外部资源,SvelteKit 会用相对路径替换 %sveltekit.assets% 并引用构建产物,但从 $app/paths 导入的 baseassets 会按配置指定。

预渲染(prerender)

详见 预渲染

concurrency?: number;
  • 默认 1

可以同时预渲染多少个页面。尽管 JavaScript 是单线程的,但如果预渲染性能受网络限制(例如从远程 CMS 加载内容),在等待网络响应时处理其他任务可以提高速度。

crawl?: boolean;
  • 默认 true

SvelteKit 是否通过从 entries 中的链接来查找预渲染的页面。

entries?: var Array: ArrayConstructorArray<'*' | `/${string}`>;
  • 默认 ["*"]

一个包含待预渲染页面,或用于开始爬取的数组(如果 crawl: true)。字符串 * 包括所有不含必填 [parameters] 的路由,可选参数为空(因为 SvelteKit 无法知道参数的值应该是什么)。

handleHttpError?: PrerenderHttpErrorHandlerValue;
  • 默认 "fail"
  • v1.15.7 可用

如何处理预渲染应用时遇到的 HTTP 错误。

  • 'fail' — 构建失败
  • 'ignore' - 安静地忽略错误并继续
  • 'warn' — 继续但打印警告
  • (details) => void — 一个使用带有 statuspathreferrerreferenceTypemessage 属性的 details 对象的自定义错误处理器。如果在该函数中 throw,构建将失败
svelte.config
/** @type {import('@sveltejs/kit').Config} */
const 
const config: {
    kit: {
        prerender: {
 handleHttpError: ({ path, referrer, message }: {
   path: any;
   referrer: any;
     message: any;
 }) => void;
        };
    };
}
@type{import('@sveltejs/kit').Config}
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: anypath, referrer: anyreferrer, message: anymessage }) => {
// 忽略指向有设计感的404页面的链接 if (path: anypath === '/not-found' && referrer: anyreferrer === '/blog/how-we-built-our-404-page') { return; } // 否则,构建失败 throw new
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error
(message: anymessage);
} } } };
handleMissingId?: PrerenderMissingIdHandlerValue;
  • 默认 "fail"
  • v1.15.7 可用

当一个预渲染页面的哈希链接没有对应的目标页面中的 id 时,该如何响应。

  • 'fail' — 构建失败
  • 'ignore' - 安静地忽略错误并继续
  • 'warn' — 继续但打印警告
  • (details) => void — 一个使用带有 pathidreferrersmessage 属性的 details 对象的自定义错误处理器。如果在该函数中 throw,构建将失败
handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue;
  • 默认 "fail"
  • v1.16.0 可用

当由 entries 导出的条目与生成它的路由不匹配时,该如何响应。

  • 'fail' — 构建失败
  • 'ignore' - 安静地忽略错误并继续
  • 'warn' — 继续但打印警告
  • (details) => void — 一个使用带有 generatedFromIdentrymatchedIdmessage 属性的 details 对象的自定义错误处理器。如果在该函数中 throw,构建将失败
var origin: stringorigin?: 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: stringfilepath: 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

+layout
<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
@deprecated
name
?: string;

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

例如,要使用当前的提交哈希,您可以通过 git rev-parse HEAD

svelte.config
import * as module "node:child_process"child_process from 'node:child_process';

export default {
	
kit: {
    version: {
        name: string;
    };
}
kit
: {
version: {
    name: string;
}
version
: {
name: stringname: 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.

@sincev0.11.12
@paramcommand The command to run.
@returnThe stdout from the command.
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 &#x3C; 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é
@sincev0.1.90
@paramencoding The character encoding to use.
@paramstart The byte offset to start decoding at.
@paramend The byte offset to stop decoding at (not inclusive).
toString
().String.trim(): string

Removes the leading and trailing white space and line terminator characters from a string.

trim
()
} } };
pollInterval?: number;
  • 默认 0

轮询版本变化的时间间隔(单位:毫秒)。如果设置为 0,则不会进行轮询。

在 GitHub 编辑此页面

上一页 下一页