Skip to main content
SvelteKit高级

Hooks

“Hooks” 是您声明的应用程序范围的函数，SvelteKit 会在响应特定事件时调用它们，让您能够对框架的行为进行更为精细的控制。

有三个 hook 文件，都是可选的：

  • src/hooks.server.js — 您的应用程序的服务端 hook
  • src/hooks.client.js — 您的应用程序的客户端 hook
  • src/hooks.js — 您的应用程序的在客户端和服务端都运行的 hook

这些模块中的代码会在应用程序启动时运行，这使得它们对初始化数据库客户端等操作很有用。

您可以通过 config.kit.files.hooks 配置这些文件的位置。

服务端 hook

以下 hook 可以添加到 src/hooks.server.js 中：

handle

这个函数在 SvelteKit 服务端每次接收到 request 时运行 — 无论是在应用程序运行时，还是在预渲染过程中 — 并决定response。

它接收一个表示请求的 event 对象和一个名为 resolve 的函数，该函数渲染路由并生成一个 Response。这允许您修改响应头或响应体，或完全绕过 SvelteKit（例如，用于以编程方式实现路由）。

src/hooks.server
/** @type {import('@sveltejs/kit').Handle} */
export async function 
function handle({ event, resolve }: {
    event: any;
    resolve: any;
}): Promise<any>
@type{import('@sveltejs/kit').Handle}
handle({ event: anyevent, resolve: anyresolve }) {
	if (event: anyevent.url.pathname.startsWith('/custom')) {
		return new var Response: new (body?: BodyInit | null, init?: ResponseInit) => Response
This Fetch API interface represents the response to a request.


MDN Reference


Response('custom response');
	}

	const const response: anyresponse = await resolve: anyresolve(event: anyevent);
	return const response: anyresponse;
}
import type { 
type Handle = (input: {
    event: RequestEvent;
    resolve(event: RequestEvent, opts?: ResolveOptions): MaybePromise<Response>;
}) => MaybePromise<...>
The handle hook runs every time the SvelteKit server receives a request and
determines the response.
It receives an event object representing the request and a function called resolve, which renders the route and generates a Response.
This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).


Handle } from '@sveltejs/kit';

export const const handle: Handlehandle: 
type Handle = (input: {
    event: RequestEvent;
    resolve(event: RequestEvent, opts?: ResolveOptions): MaybePromise<Response>;
}) => MaybePromise<...>
The handle hook runs every time the SvelteKit server receives a request and
determines the response.
It receives an event object representing the request and a function called resolve, which renders the route and generates a Response.
This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).


Handle = async ({ event: RequestEvent<Partial<Record<string, string>>, string | null>event, resolve: (event: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>resolve }) => {
	if (event: RequestEvent<Partial<Record<string, string>>, string | null>event.RequestEvent<Partial<Record<string, string>>, string | null>.url: URL
The requested URL.


url.URL.pathname: string
MDN Reference


pathname.String.startsWith(searchString: string, position?: number): boolean
Returns true if the sequence of elements of searchString converted to a String is the
same as the corresponding elements of this object (converted to a String) starting at
position. Otherwise returns false.


startsWith('/custom')) {
		return new var Response: new (body?: BodyInit | null, init?: ResponseInit) => Response
This Fetch API interface represents the response to a request.


MDN Reference


Response('custom response');
	}

	const const response: Responseresponse = await resolve: (event: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>resolve(event: RequestEvent<Partial<Record<string, string>>, string | null>event);
	return const response: Responseresponse;
};

对静态资源的请求 — 包括已经预渲染的页面 — 不会由 SvelteKit 处理。

如果未实现，默认为 ({ event, resolve }) => resolve(event)。

locals

要向请求中添加自定义数据（这些数据会传递给 +server.js 中的处理程序和服务端的 load 函数），可以填充 event.locals 对象，如下所示。

src/hooks.server
/** @type {import('@sveltejs/kit').Handle} */
export async function 
function handle(input: {
    event: RequestEvent;
    resolve(event: RequestEvent, opts?: ResolveOptions): MaybePromise<Response>;
}): MaybePromise<...>
@type{import('@sveltejs/kit').Handle}
handle({ event: RequestEvent<Partial<Record<string, string>>, string | null>event, resolve: (event: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>resolve }) {
	event: RequestEvent<Partial<Record<string, string>>, string | null>event.RequestEvent<Partial<Record<string, string>>, string | null>.locals: App.Locals
Contains custom data that was added to the request within the server handle hook.


locals.App.Locals.user: Useruser = await const getUserInformation: (cookie: string | void) => Promise<User>getUserInformation(event: RequestEvent<Partial<Record<string, string>>, string | null>event.RequestEvent<Partial<Record<string, string>>, string | null>.cookies: Cookies
Get or set cookies related to the current request


cookies.Cookies.get(name: string, opts?: CookieParseOptions): string | undefined
Gets a cookie that was previously set with cookies.set, or from the request headers.


@paramname the name of the cookie
@paramopts the options, passed directly to cookie.parse. See documentation here
get('sessionid'));

	const const response: Responseresponse = await resolve: (event: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>resolve(event: RequestEvent<Partial<Record<string, string>>, string | null>event);
	const response: Responseresponse.Response.headers: Headers
MDN Reference


headers.Headers.set(name: string, value: string): void
MDN Reference


set('x-custom-header', 'potato');

	return const response: Responseresponse;
}
import type { 
type Handle = (input: {
    event: RequestEvent;
    resolve(event: RequestEvent, opts?: ResolveOptions): MaybePromise<Response>;
}) => MaybePromise<...>
The handle hook runs every time the SvelteKit server receives a request and
determines the response.
It receives an event object representing the request and a function called resolve, which renders the route and generates a Response.
This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).


Handle } from '@sveltejs/kit';

export const const handle: Handlehandle: 
type Handle = (input: {
    event: RequestEvent;
    resolve(event: RequestEvent, opts?: ResolveOptions): MaybePromise<Response>;
}) => MaybePromise<...>
The handle hook runs every time the SvelteKit server receives a request and
determines the response.
It receives an event object representing the request and a function called resolve, which renders the route and generates a Response.
This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).


Handle = async ({ event: RequestEvent<Partial<Record<string, string>>, string | null>event, resolve: (event: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>resolve }) => {
	event: RequestEvent<Partial<Record<string, string>>, string | null>event.RequestEvent<Partial<Record<string, string>>, string | null>.locals: App.Locals
Contains custom data that was added to the request within the server handle hook.


locals.App.Locals.user: Useruser = await const getUserInformation: (cookie: string | void) => Promise<User>getUserInformation(event: RequestEvent<Partial<Record<string, string>>, string | null>event.RequestEvent<Partial<Record<string, string>>, string | null>.cookies: Cookies
Get or set cookies related to the current request


cookies.Cookies.get(name: string, opts?: CookieParseOptions): string | undefined
Gets a cookie that was previously set with cookies.set, or from the request headers.


@paramname the name of the cookie
@paramopts the options, passed directly to cookie.parse. See documentation here
get('sessionid'));

	const const response: Responseresponse = await resolve: (event: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>resolve(event: RequestEvent<Partial<Record<string, string>>, string | null>event);
	const response: Responseresponse.Response.headers: Headers
MDN Reference


headers.Headers.set(name: string, value: string): void
MDN Reference


set('x-custom-header', 'potato');

	return const response: Responseresponse;
};

您可以定义多个 handle 函数，并使用sequence 辅助函数执行它们。

resolve 还支持第二个可选参数，让您能够更好地控制响应的渲染方式。该参数是一个对象，可以包含以下字段：

  • transformPageChunk(opts: { html: string, done: boolean }): MaybePromise<string | undefined> — 对 HTML 应用自定义转换。如果 done 为 true，则是最后一个块。块不保证是格式良好的 HTML（例如，它们可能包含一个元素的开始标签但没有结束标签），但它们总是会在合理的边界处分割，比如 %sveltekit.head% 或布局/页面组件。
  • filterSerializedResponseHeaders(name: string, value: string): boolean — 确定当 load 函数使用 fetch 加载资源时，哪些头部应该包含在序列化的响应中。默认情况下，不会包含任何头部。
  • preload(input: { type: 'js' | 'css' | 'font' | 'asset', path: string }): boolean — 确定应该在 <head> 标签中添加哪些文件以预加载。该方法在构建代码块时被调用，每个找到的文件都会被调用 — 例如，如果您在 +page.svelte 中有 import './styles.css，在访问该页面时，preload 将传入该 CSS 文件的解析路径进行调用。注意，在开发模式下不会调用 preload，因为它依赖于构建时的分析。预加载可以通过更早下载资源来提高性能，但如果不必要地下载太多内容也会适得其反。默认情况下，会预加载 js 和 css 文件。目前不会预加载 asset 文件，但我们可能会在评估反馈后添加此功能。
src/hooks.server
/** @type {import('@sveltejs/kit').Handle} */
export async function 
function handle({ event, resolve }: {
    event: any;
    resolve: any;
}): Promise<any>
@type{import('@sveltejs/kit').Handle}
handle({ event: anyevent, resolve: anyresolve }) {
	const const response: anyresponse = await resolve: anyresolve(event: anyevent, {
		
transformPageChunk: ({ html }: {
    html: any;
}) => any
transformPageChunk: ({ html: anyhtml }) => html: anyhtml.replace('old', 'new'),
		filterSerializedResponseHeaders: (name: any) => anyfilterSerializedResponseHeaders: (name: anyname) => name: anyname.startsWith('x-'),
		
preload: ({ type, path }: {
    type: any;
    path: any;
}) => any
preload: ({ type: anytype, path: anypath }) => type: anytype === 'js' || path: anypath.includes('/important/')
	});

	return const response: anyresponse;
}
import type { 
type Handle = (input: {
    event: RequestEvent;
    resolve(event: RequestEvent, opts?: ResolveOptions): MaybePromise<Response>;
}) => MaybePromise<...>
The handle hook runs every time the SvelteKit server receives a request and
determines the response.
It receives an event object representing the request and a function called resolve, which renders the route and generates a Response.
This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).


Handle } from '@sveltejs/kit';

export const const handle: Handlehandle: 
type Handle = (input: {
    event: RequestEvent;
    resolve(event: RequestEvent, opts?: ResolveOptions): MaybePromise<Response>;
}) => MaybePromise<...>
The handle hook runs every time the SvelteKit server receives a request and
determines the response.
It receives an event object representing the request and a function called resolve, which renders the route and generates a Response.
This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).


Handle = async ({ event: RequestEvent<Partial<Record<string, string>>, string | null>event, resolve: (event: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>resolve }) => {
	const const response: Responseresponse = await resolve: (event: RequestEvent, opts?: ResolveOptions) => MaybePromise<Response>resolve(event: RequestEvent<Partial<Record<string, string>>, string | null>event, {
		
ResolveOptions.transformPageChunk?(input: {
    html: string;
    done: boolean;
}): MaybePromise<string | undefined>
Applies custom transforms to HTML. If done is true, it’s the final chunk. Chunks are not guaranteed to be well-formed HTML
(they could include an element’s opening tag but not its closing tag, for example)
but they will always be split at sensible boundaries such as %sveltekit.head% or layout/page components.


@paraminput the html chunk and the info if this is the last chunk
transformPageChunk: ({ html: stringhtml }) => html: stringhtml.String.replace(searchValue: string | RegExp, replaceValue: string): string (+3 overloads)
Replaces text in a string, using a regular expression or search string.


@paramsearchValue A string or regular expression to search for.
@paramreplaceValue A string containing the text to replace. When the {@linkcode searchValue} is a RegExp, all matches are replaced if the g flag is set (or only those matches at the beginning, if the y flag is also present). Otherwise, only the first match of {@linkcode searchValue} is replaced.
replace('old', 'new'),
		ResolveOptions.filterSerializedResponseHeaders?(name: string, value: string): boolean
Determines which headers should be included in serialized responses when a load function loads a resource with fetch.
By default, none will be included.


@paramname header name
@paramvalue header value
filterSerializedResponseHeaders: (name: stringname) => name: stringname.String.startsWith(searchString: string, position?: number): boolean
Returns true if the sequence of elements of searchString converted to a String is the
same as the corresponding elements of this object (converted to a String) starting at
position. Otherwise returns false.


startsWith('x-'),
		
ResolveOptions.preload?(input: {
    type: "font" | "css" | "js" | "asset";
    path: string;
}): boolean
Determines what should be added to the &#x3C;head> tag to preload it.
By default, js and css files will be preloaded.


@paraminput the type of the file and its path
preload: ({ type: "font" | "css" | "js" | "asset"type, path: stringpath }) => type: "font" | "css" | "js" | "asset"type === 'js' || path: stringpath.String.includes(searchString: string, position?: number): boolean
Returns true if searchString appears as a substring of the result of converting this
object to a String, at one or more positions that are
greater than or equal to position; otherwise, returns false.


@paramsearchString search string
@paramposition If position is undefined, 0 is assumed, so as to search all of the String.
includes('/important/')
	});

	return const response: Responseresponse;
};

注意，resolve(...) 永远不会抛出错误，它总是会返回一个带有适当状态码的 Promise<Response>。如果在 handle 期间其他地方抛出错误，这将被视为致命错误，SvelteKit 将根据 Accept 头部返回错误的 JSON 表示或回退错误页面 — 后者可以通过 src/error.html 自定义。您可以在这里阅读更多关于错误处理的信息。

handleFetch

这个函数允许您修改（或替换）在服务端上运行的 load 或 action 函数中发生的 fetch 请求（或在预渲染期间）。

例如，当用户执行客户端导航到相应页面时，您的 load 函数可能会向公共 URL（如 https://api.yourapp.com）发出请求，但在 SSR 期间，直接访问 API 可能更有意义（绕过位于它和公共互联网之间的代理和负载均衡器）。

src/hooks.server
/** @type {import('@sveltejs/kit').HandleFetch} */
export async function 
function handleFetch({ request, fetch }: {
    request: any;
    fetch: any;
}): Promise<any>
@type{import('@sveltejs/kit').HandleFetch}
handleFetch({ request: anyrequest, fetch: anyfetch }) {
	if (request: anyrequest.url.startsWith('https://api.yourapp.com/')) {
		// 克隆原始请求，但改变 URL
		request: anyrequest = new var Request: new (input: RequestInfo | URL, init?: RequestInit) => Request
This Fetch API interface represents a resource request.


MDN Reference


Request(
			request: anyrequest.url.replace('https://api.yourapp.com/', 'http://localhost:9999/'),
			request: anyrequest
		);
	}

	return fetch: anyfetch(request: anyrequest);
}
import type { 
type HandleFetch = (input: {
    event: RequestEvent;
    request: Request;
    fetch: typeof fetch;
}) => MaybePromise<Response>
The handleFetch hook allows you to modify (or replace) a fetch request that happens inside a load function that runs on the server (or during pre-rendering)


HandleFetch } from '@sveltejs/kit';

export const const handleFetch: HandleFetchhandleFetch: 
type HandleFetch = (input: {
    event: RequestEvent;
    request: Request;
    fetch: typeof fetch;
}) => MaybePromise<Response>
The handleFetch hook allows you to modify (or replace) a fetch request that happens inside a load function that runs on the server (or during pre-rendering)


HandleFetch = async ({ request: Requestrequest, 
fetch: {
    (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
    (input: string | URL | globalThis.Request, init?: RequestInit): Promise<Response>;
}
fetch }) => {
	if (request: Requestrequest.Request.url: string
Returns the URL of request as a string.


MDN Reference


url.String.startsWith(searchString: string, position?: number): boolean
Returns true if the sequence of elements of searchString converted to a String is the
same as the corresponding elements of this object (converted to a String) starting at
position. Otherwise returns false.


startsWith('https://api.yourapp.com/')) {
		// 克隆原始请求，但改变 URL
		request: Requestrequest = new var Request: new (input: RequestInfo | URL, init?: RequestInit) => Request
This Fetch API interface represents a resource request.


MDN Reference


Request(
			request: Requestrequest.Request.url: string
Returns the URL of request as a string.


MDN Reference


url.String.replace(searchValue: string | RegExp, replaceValue: string): string (+3 overloads)
Replaces text in a string, using a regular expression or search string.


@paramsearchValue A string or regular expression to search for.
@paramreplaceValue A string containing the text to replace. When the {@linkcode searchValue} is a RegExp, all matches are replaced if the g flag is set (or only those matches at the beginning, if the y flag is also present). Otherwise, only the first match of {@linkcode searchValue} is replaced.
replace('https://api.yourapp.com/', 'http://localhost:9999/'),
			request: Requestrequest
		);
	}

	return fetch: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response> (+1 overload)
MDN Reference


fetch(request: Requestrequest);
};

认证凭据

对于同源请求，除非 credentials 选项设置为 "omit"，否则 SvelteKit 的 fetch 实现会转发 cookie 和 authorization 头部。

对于跨源请求，如果请求 URL 属于应用程序的子域，则会包含 cookie — 例如，如果您的应用程序在 my-domain.com 上，而您的 API 在 api.my-domain.com 上，cookie 将包含在请求中。

如果您的应用程序和 API 在兄弟子域上 — 例如 www.my-domain.com 和 api.my-domain.com — 那么属于共同父域（如 my-domain.com）的 cookie 将不会被包含，因为 SvelteKit 无法知道 cookie 属于哪个域。在这些情况下，您需要使用 handleFetch 手动包含 cookie：

src/hooks.server
/** @type {import('@sveltejs/kit').HandleFetch} */
export async function 
function handleFetch({ event, request, fetch }: {
    event: any;
    request: any;
    fetch: any;
}): Promise<any>
@type{import('@sveltejs/kit').HandleFetch}
handleFetch({ event: anyevent, request: anyrequest, fetch: anyfetch }) {
	if (request: anyrequest.url.startsWith('https://api.my-domain.com/')) {
		request: anyrequest.headers.set('cookie', event: anyevent.request.headers.get('cookie'));
	}

	return fetch: anyfetch(request: anyrequest);
}
import type { 
type HandleFetch = (input: {
    event: RequestEvent;
    request: Request;
    fetch: typeof fetch;
}) => MaybePromise<Response>
The handleFetch hook allows you to modify (or replace) a fetch request that happens inside a load function that runs on the server (or during pre-rendering)


HandleFetch } from '@sveltejs/kit';
export const const handleFetch: HandleFetchhandleFetch: 
type HandleFetch = (input: {
    event: RequestEvent;
    request: Request;
    fetch: typeof fetch;
}) => MaybePromise<Response>
The handleFetch hook allows you to modify (or replace) a fetch request that happens inside a load function that runs on the server (or during pre-rendering)


HandleFetch = async ({ event: RequestEvent<Partial<Record<string, string>>, string | null>event, request: Requestrequest, 
fetch: {
    (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
    (input: string | URL | globalThis.Request, init?: RequestInit): Promise<Response>;
}
fetch }) => {
	if (request: Requestrequest.Request.url: string
Returns the URL of request as a string.


MDN Reference


url.String.startsWith(searchString: string, position?: number): boolean
Returns true if the sequence of elements of searchString converted to a String is the
same as the corresponding elements of this object (converted to a String) starting at
position. Otherwise returns false.


startsWith('https://api.my-domain.com/')) {
		request: Requestrequest.Request.headers: Headers
Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the “Host” header.


MDN Reference


headers.Headers.set(name: string, value: string): void
MDN Reference


set('cookie', event: RequestEvent<Partial<Record<string, string>>, string | null>event.RequestEvent<Partial<Record<string, string>>, string | null>.request: Request
The original request object


request.Request.headers: Headers
Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the “Host” header.


MDN Reference


headers.Headers.get(name: string): string | null
MDN Reference


get('cookie'));
	}

	return fetch: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response> (+1 overload)
MDN Reference


fetch(request: Requestrequest);
};

共享 hook

以下 hook 可以同时添加到 src/hooks.server.js 和 src/hooks.client.js 中：

handleError

如果在加载或渲染期间抛出意外错误，此函数将被调用，并传入 error、event、status 代码和 message。这允许两件事：

  • 您可以记录错误
  • 您可以生成一个安全的、显示给用户的自定义错误表示，省略敏感的详细信息，如消息和堆栈跟踪。返回的值（默认为 { message }）会成为 $page.error 的值。

对于从您的代码（或您的代码调用的库代码）抛出的错误，状态将为 500，消息将为 “Internal Error”。虽然 error.message 可能包含不应暴露给用户的敏感信息，但 message 是安全的（尽管对普通用户来说没有意义）。

要以类型安全的方式向 $page.error 对象添加更多信息，您可以通过声明 App.Error 接口（必须包含 message: string，以保证合理的回退行为）来自定义预期的形状。这允许您 — 例如 — 附加一个跟踪 ID，供用户在与技术支持人员通信时引用：

src/app.d
declare global {
	namespace App {
		interface interface App.Error
Defines the common shape of expected and unexpected errors. Expected errors are thrown using the error function. Unexpected errors are handled by the handleError hooks which should return this shape.


Error {
			App.Error.message: stringmessage: string;
			App.Error.errorId: stringerrorId: string;
		}
	}
}

export {};
src/hooks.server
import * as module "@sentry/sveltekit"Sentry from '@sentry/sveltekit';

module "@sentry/sveltekit"Sentry.const init: (opts: any) => voidinit({/*...*/})

/** @type {import('@sveltejs/kit').HandleServerError} */
export async function 
function handleError(input: {
    error: unknown;
    event: RequestEvent;
    status: number;
    message: string;
}): MaybePromise<void | App.Error>
@type{import('@sveltejs/kit').HandleServerError}
handleError({ error: unknownerror, event: RequestEvent<Partial<Record<string, string>>, string | null>event, status: numberstatus, message: stringmessage }) {
	const const errorId: `${string}-${string}-${string}-${string}-${string}`errorId = var crypto: Crypto
MDN Reference


crypto.Crypto.randomUUID(): `${string}-${string}-${string}-${string}-${string}`
Available only in secure contexts.


MDN Reference


randomUUID();

	// 与 https://sentry.io/ 集成的示例
	module "@sentry/sveltekit"Sentry.const captureException: (error: any, opts: any) => voidcaptureException(error: unknownerror, {
		
extra: {
    event: RequestEvent<Partial<Record<string, string>>, string | null>;
    errorId: `${string}-${string}-${string}-${string}-${string}`;
    status: number;
}
extra: { event: RequestEvent<Partial<Record<string, string>>, string | null>event, errorId: `${string}-${string}-${string}-${string}-${string}`errorId, status: numberstatus }
	});

	return {
		App.Error.message: stringmessage: '哎呀！',
		errorId: `${string}-${string}-${string}-${string}-${string}`errorId
	};
}
import * as module "@sentry/sveltekit"Sentry from '@sentry/sveltekit';
import type { 
type HandleServerError = (input: {
    error: unknown;
    event: RequestEvent;
    status: number;
    message: string;
}) => MaybePromise<void | App.Error>
The server-side handleError hook runs when an unexpected error is thrown while responding to a request.


If an unexpected error is thrown during loading or rendering, this function will be called with the error and the event.
Make sure that this function never throws an error.


HandleServerError } from '@sveltejs/kit';

module "@sentry/sveltekit"Sentry.const init: (opts: any) => voidinit({/*...*/})

export const const handleError: HandleServerErrorhandleError: 
type HandleServerError = (input: {
    error: unknown;
    event: RequestEvent;
    status: number;
    message: string;
}) => MaybePromise<void | App.Error>
The server-side handleError hook runs when an unexpected error is thrown while responding to a request.


If an unexpected error is thrown during loading or rendering, this function will be called with the error and the event.
Make sure that this function never throws an error.


HandleServerError = async ({ error: unknownerror, event: RequestEvent<Partial<Record<string, string>>, string | null>event, status: numberstatus, message: stringmessage }) => {
	const const errorId: `${string}-${string}-${string}-${string}-${string}`errorId = var crypto: Crypto
MDN Reference


crypto.Crypto.randomUUID(): `${string}-${string}-${string}-${string}-${string}`
Available only in secure contexts.


MDN Reference


randomUUID();

	// 与 https://sentry.io/ 集成的示例
	module "@sentry/sveltekit"Sentry.const captureException: (error: any, opts: any) => voidcaptureException(error: unknownerror, {
		
extra: {
    event: RequestEvent<Partial<Record<string, string>>, string | null>;
    errorId: `${string}-${string}-${string}-${string}-${string}`;
    status: number;
}
extra: { event: RequestEvent<Partial<Record<string, string>>, string | null>event, errorId: `${string}-${string}-${string}-${string}-${string}`errorId, status: numberstatus }
	});

	return {
		App.Error.message: stringmessage: '哎呀！',
		errorId: `${string}-${string}-${string}-${string}-${string}`errorId
	};
};
src/hooks.client
import * as module "@sentry/sveltekit"Sentry from '@sentry/sveltekit';

module "@sentry/sveltekit"Sentry.const init: (opts: any) => voidinit({/*...*/})

/** @type {import('@sveltejs/kit').HandleClientError} */
export async function 
function handleError(input: {
    error: unknown;
    event: NavigationEvent;
    status: number;
    message: string;
}): MaybePromise<void | App.Error>
@type{import('@sveltejs/kit').HandleClientError}
handleError({ error: unknownerror, event: NavigationEvent<Partial<Record<string, string>>, string | null>event, status: numberstatus, message: stringmessage }) {
	const const errorId: `${string}-${string}-${string}-${string}-${string}`errorId = var crypto: Crypto
MDN Reference


crypto.Crypto.randomUUID(): `${string}-${string}-${string}-${string}-${string}`
Available only in secure contexts.


MDN Reference


randomUUID();

	// 与 https://sentry.io/ 集成的示例
	module "@sentry/sveltekit"Sentry.const captureException: (error: any, opts: any) => voidcaptureException(error: unknownerror, {
		
extra: {
    event: NavigationEvent<Partial<Record<string, string>>, string | null>;
    errorId: `${string}-${string}-${string}-${string}-${string}`;
    status: number;
}
extra: { event: NavigationEvent<Partial<Record<string, string>>, string | null>event, errorId: `${string}-${string}-${string}-${string}-${string}`errorId, status: numberstatus }
	});

	return {
		App.Error.message: stringmessage: '哎呀！',
		errorId: `${string}-${string}-${string}-${string}-${string}`errorId
	};
}
import * as module "@sentry/sveltekit"Sentry from '@sentry/sveltekit';
import type { 
type HandleClientError = (input: {
    error: unknown;
    event: NavigationEvent;
    status: number;
    message: string;
}) => MaybePromise<void | App.Error>
The client-side handleError hook runs when an unexpected error is thrown while navigating.


If an unexpected error is thrown during loading or the following render, this function will be called with the error and the event.
Make sure that this function never throws an error.


HandleClientError } from '@sveltejs/kit';

module "@sentry/sveltekit"Sentry.const init: (opts: any) => voidinit({/*...*/})

export const const handleError: HandleClientErrorhandleError: 
type HandleClientError = (input: {
    error: unknown;
    event: NavigationEvent;
    status: number;
    message: string;
}) => MaybePromise<void | App.Error>
The client-side handleError hook runs when an unexpected error is thrown while navigating.


If an unexpected error is thrown during loading or the following render, this function will be called with the error and the event.
Make sure that this function never throws an error.


HandleClientError = async ({ error: unknownerror, event: NavigationEvent<Partial<Record<string, string>>, string | null>event, status: numberstatus, message: stringmessage }) => {
	const const errorId: `${string}-${string}-${string}-${string}-${string}`errorId = var crypto: Crypto
MDN Reference


crypto.Crypto.randomUUID(): `${string}-${string}-${string}-${string}-${string}`
Available only in secure contexts.


MDN Reference


randomUUID();

	// 与 https://sentry.io/ 集成的示例
	module "@sentry/sveltekit"Sentry.const captureException: (error: any, opts: any) => voidcaptureException(error: unknownerror, {
		
extra: {
    event: NavigationEvent<Partial<Record<string, string>>, string | null>;
    errorId: `${string}-${string}-${string}-${string}-${string}`;
    status: number;
}
extra: { event: NavigationEvent<Partial<Record<string, string>>, string | null>event, errorId: `${string}-${string}-${string}-${string}-${string}`errorId, status: numberstatus }
	});

	return {
		App.Error.message: stringmessage: '哎呀！',
		errorId: `${string}-${string}-${string}-${string}-${string}`errorId
	};
};

在 src/hooks.client.js 中，handleError 的类型是 HandleClientError 而不是 HandleServerError，并且 event 是一个 NavigationEvent 而不是 RequestEvent。

此函数不会因为预期的错误（那些使用从 @sveltejs/kit 导入的 error 函数抛出的错误）而被调用。

在开发过程中，如果由于 Svelte 代码中的语法错误而发生错误，传入的错误会附加一个 frame 属性，突出显示错误的位置。

确保 handleError 永远不会抛出错误

init

这个函数在服务端创建或应用程序在浏览器中启动时运行一次，是执行异步工作（如初始化数据库连接）的有用位置。

如果您的环境支持顶级 await，init 函数实际上与在模块顶层编写初始化逻辑没有什么不同，但一些环境 — 尤其是 Safari — 不支持。

src/hooks.server
import * as import dbdb from '$lib/server/database';

/** @type {import('@sveltejs/kit').ServerInit} */
export async function function init(): Promise<void>
@type{import('@sveltejs/kit').ServerInit}
init() {
	await import dbdb.connect();
}
import * as import dbdb from '$lib/server/database';
import type { type ServerInit = () => MaybePromise<void>
The init will be invoked before the server responds to its first request


@since2.10.0
ServerInit } from '@sveltejs/kit';

export const const init: ServerInitinit: type ServerInit = () => MaybePromise<void>
The init will be invoked before the server responds to its first request


@since2.10.0
ServerInit = async () => {
	await import dbdb.connect();
};

在浏览器中，init 中的异步工作会延迟水合，所以要注意您在那里放什么。

通用 hook

以下 hook 可以添加到 src/hooks.js 中。通用 hook 在服务端和客户端都运行（不要与共享 hook 混淆，后者是特定环境的）。

reroute

这个函数在 handle 之前运行，允许您更改 URL 如何转换为路由。返回的路径名（默认为 url.pathname）用于选择路由及其参数。

例如，您可能有一个 src/routes/[[lang]]/about/+page.svelte 页面，它应该可以访问为 /en/about 或 /de/ueber-uns 或 /fr/a-propos。您可以用 reroute 来实现：

src/hooks

/** @type {Record<string, string>} */
const 
const translated: {
    '/en/about': string;
    '/de/ueber-uns': string;
    '/fr/a-propos': string;
}
@type{Record<string, string>}
translated = {
	'/en/about': '/en/about',
	'/de/ueber-uns': '/de/about',
	'/fr/a-propos': '/fr/about'
};

/** @type {import('@sveltejs/kit').Reroute} */
export function 
function reroute({ url }: {
    url: any;
}): any
@type{import('@sveltejs/kit').Reroute}
reroute({ url: anyurl }) {
	if (url: anyurl.pathname in 
const translated: {
    '/en/about': string;
    '/de/ueber-uns': string;
    '/fr/a-propos': string;
}
@type{Record<string, string>}
translated) {
		return 
const translated: {
    '/en/about': string;
    '/de/ueber-uns': string;
    '/fr/a-propos': string;
}
@type{Record<string, string>}
translated[url: anyurl.pathname];
	}
}
import type { 
type Reroute = (event: {
    url: URL;
}) => void | string
The reroute hook allows you to modify the URL before it is used to determine which route to render.


@since2.3.0
Reroute } from '@sveltejs/kit';

const const translated: Record<string, string>translated: 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, string> = {
	'/en/about': '/en/about',
	'/de/ueber-uns': '/de/about',
	'/fr/a-propos': '/fr/about'
};

export const const reroute: Reroutereroute: 
type Reroute = (event: {
    url: URL;
}) => void | string
The reroute hook allows you to modify the URL before it is used to determine which route to render.


@since2.3.0
Reroute = ({ url: URLurl }) => {
	if (url: URLurl.URL.pathname: string
MDN Reference


pathname in const translated: Record<string, string>translated) {
		return const translated: Record<string, string>translated[url: URLurl.URL.pathname: string
MDN Reference


pathname];
	}
};

lang 参数将从返回的路径名正确派生。

使用 reroute 不会改变浏览器地址栏的内容，也不会改变 event.url 的值。

传输

这是一组 传输器，允许您跨服务端/客户端边界传递自定义类型 - 从 load 和 form actions 返回的类型。每个传输器都包含一个 encode 函数，该函数对服务端上的值进行编码(或对任何不是该类型的实例返回 false)，以及一个相应的 decode 函数:

src/hooks
import { import VectorVector } from '$lib/math';

/** @type {import('@sveltejs/kit').Transport} */
export const 
const transport: {
    Vector: {
        encode: (value: any) => false | any[];
        decode: ([x, y]: [any, any]) => any;
    };
}
@type{import('@sveltejs/kit').Transport}
transport = {
	
type Vector: {
    encode: (value: any) => false | any[];
    decode: ([x, y]: [any, any]) => any;
}
Vector: {
		encode: (value: any) => false | any[]encode: (value: anyvalue) => value: anyvalue instanceof import VectorVector && [value: anyvalue.x, value: anyvalue.y],
		decode: ([x, y]: [any, any]) => anydecode: ([x: anyx, y: anyy]) => new import VectorVector(x: anyx, y: anyy)
	}
};
import { import VectorVector } from '$lib/math';
import type { 
type Transport = {
    [x: string]: Transporter<any, any>;
}
The transport hook allows you to transport custom types across the server/client boundary.


Each transporter has a pair of encode and decode functions. On the server, encode determines whether a value is an instance of the custom type and, if so, returns a non-falsy encoding of the value which can be an object or an array (or false otherwise).


In the browser, decode turns the encoding back into an instance of the custom type.


import type { Transport } from '@sveltejs/kit';

declare class MyCustomType {
	data: any
}

// hooks.js
export const transport: Transport = {
	MyCustomType: {
		encode: (value) => value instanceof MyCustomType &#x26;&#x26; [value.data],
		decode: ([data]) => new MyCustomType(data)
	}
};
@since2.11.0
Transport } from '@sveltejs/kit';

export const const transport: Transporttransport: 
type Transport = {
    [x: string]: Transporter<any, any>;
}
The transport hook allows you to transport custom types across the server/client boundary.


Each transporter has a pair of encode and decode functions. On the server, encode determines whether a value is an instance of the custom type and, if so, returns a non-falsy encoding of the value which can be an object or an array (or false otherwise).


In the browser, decode turns the encoding back into an instance of the custom type.


import type { Transport } from '@sveltejs/kit';

declare class MyCustomType {
	data: any
}

// hooks.js
export const transport: Transport = {
	MyCustomType: {
		encode: (value) => value instanceof MyCustomType &#x26;&#x26; [value.data],
		decode: ([data]) => new MyCustomType(data)
	}
};
@since2.11.0
Transport = {
	
type Vector: {
    encode: (value: any) => false | any[];
    decode: ([x, y]: any) => any;
}
Vector: {
		Transporter<any, any>.encode: (value: any) => anyencode: (value: anyvalue) => value: anyvalue instanceof import VectorVector && [value: anyvalue.x, value: anyvalue.y],
		Transporter<any, any>.decode: (data: any) => anydecode: ([x: anyx, y: anyy]) => new import VectorVector(x: anyx, y: anyy)
	}
};

进一步阅读

在 GitHub 编辑此页面

上一页 下一页
高级路由