a b c

``` # Service workers Service workers 作为代理服务端，处理应用程序内部的网络请求。这使得您的应用程序能够离线工作，但即使您不需要离线支持（或由于您正在构建的应用程序类型而无法实现它），使用 service workers 预缓存构建的 JS 和 CSS 来加快导航速度，通常也是值得的。 在 SvelteKit 中，如果您有一个 `src/service-worker.js` 文件（或 `src/service-worker/index.js`），它将被打包并自动注册。如果需要，您可以更改 [service worker 的位置](configuration#files)。 如果您需要使用自己的逻辑注册 service worker 或使用其他解决方案，可以[禁用自动注册](configuration#serviceWorker)。默认注册看起来类似这样： ```js if ('serviceWorker' in navigator) { addEventListener('load', function () { navigator.serviceWorker.register('./path/to/service-worker.js'); }); } ``` ## Service Worker 内部 在 service worker 内部，您可以访问 [`$service-worker` 模块]($service-worker)，它为您提供所有静态资源、构建文件和预渲染页面的路径。您还会获得一个应用程序版本字符串，可用于创建唯一的缓存名称，以及部署的 `base` 路径。如果您的 Vite 配置指定了 `define`（用于全局变量替换），这也将应用于 service workers 以及服务端/客户端构建。 以下示例会尽可能早的缓存构建的应用程序和 `static` 中的所有文件，并在访问时缓存所有其他请求。这将使每个页面在访问后都能离线工作。 ```js // @errors: 2339 /// import { build, files, version } from '$service-worker'; // 为此部署创建唯一的缓存名称 const CACHE = `cache-${version}`; const ASSETS = [ ...build, // 应用程序本身 ...files // `static` 中的所有内容 ]; self.addEventListener('install', (event) => { // 创建新缓存并添加所有文件 async function addFilesToCache() { const cache = await caches.open(CACHE); await cache.addAll(ASSETS); } event.waitUntil(addFilesToCache()); }); self.addEventListener('activate', (event) => { // 从磁盘删除以前的缓存数据 async function deleteOldCaches() { for (const key of await caches.keys()) { if (key !== CACHE) await caches.delete(key); } } event.waitUntil(deleteOldCaches()); }); self.addEventListener('fetch', (event) => { // 忽略 POST 请求等 if (event.request.method !== 'GET') return; async function respond() { const url = new URL(event.request.url); const cache = await caches.open(CACHE); // `build`/`files` 始终可以从缓存中提供服务 if (ASSETS.includes(url.pathname)) { const response = await cache.match(url.pathname); if (response) { return response; } } // 对于其他所有内容，首先尝试网络 // 但如果我们离线，则回退到缓存 try { const response = await fetch(event.request); // 如果我们离线，fetch 可能返回非 Response 值 // 而不是抛出错误 - 我们不能将这个非 Response 传递给 respondWith if (!(response instanceof Response)) { throw new Error('invalid response from fetch'); } if (response.status === 200) { cache.put(event.request, response.clone()); } return response; } catch (err) { const response = await cache.match(event.request); if (response) { return response; } // 如果没有缓存，就直接报错 // 因为我们无法对这个请求做任何响应 throw err; } } event.respondWith(respond()); }); ``` > [!NOTE] 缓存时要小心！在某些情况下，过时的数据可能比离线时无法获取的数据更糟糕。由于浏览器会在缓存太满时清空缓存，因此您还应该谨慎缓存大型资源，如视频文件。 ## 在开发过程中 service worker 在生产环境中会被打包，但在开发过程中不会。因此，只有支持 [service workers 中的模块](https://web.dev/es-modules-in-sw) 的浏览器才能在开发时使用它们。如果您手动注册 service worker，在开发时需要传递 `{ type: 'module' }` 选项： ```js import { dev } from '$app/environment'; navigator.serviceWorker.register('/service-worker.js', { type: dev ? 'module' : 'classic' }); ``` > [!NOTE] 在开发环境中，`build` 和 `prerendered` 是空数组 ## 类型安全 为 service workers 设置适当的类型需要一些手动设置。在您的 `service-worker.js` 中，在文件顶部添加以下内容： ```original-js /// /// /// /// const sw = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (self)); ``` ```generated-ts /// /// /// /// const sw = self as unknown as ServiceWorkerGlobalScope; ``` 这会禁用对 service worker 中不可用的 DOM 类型（如 `HTMLElement`）的访问，并实例化正确的全局变量。将 `self` 重新赋值给 `sw` 允许您在此过程中进行类型转换（有几种方法可以做到这一点，但这是最简单的，不需要额外的文件）。在文件的其余部分使用 `sw` 而不是 `self`。 对 SvelteKit 类型的引用确保 `$service-worker` 导入具有适当的类型定义。如果您导入 `$env/static/public`，您要么必须使用 `// @ts-ignore` 注释导入，要么添加 `/// ` 到引用类型中。 ## 其他解决方案 SvelteKit 的 service worker 实现故意保持低级别。如果您需要更全功能但也更有主见的解决方案，我们建议查看像 [Vite PWA 插件](https://vite-pwa-org.netlify.app/frameworks/sveltekit.html) 这样的解决方案，它使用 [Workbox](https://web.dev/learn/pwa/workbox)。有关 service workers 的更多一般信息，我们推荐 [MDN web 文档](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers)。 # 仅服务端模块 SvelteKit 会像一个好朋友一样，保守您的秘密。在同一个代码仓库中编写后端和前端代码时，很容易不小心将敏感数据（例如包含 API 密钥的环境变量）导入到前端代码中。SvelteKit 提供了一种完全防止这种情况发生的方法：仅服务端模块（server-only modules）。 ## 私有环境变量 [`$env/static/private`]($env-static-private) 和 [`$env/dynamic/private`]($env-dynamic-private) 模块只能导入到仅在服务端上运行的模块中，例如 [`hooks.server.js`](hooks#Server-hooks) 或 [`+page.server.js`](routing#page-page.server.js)。 ## 仅服务端工具 [`$app/server`]($app-server) 模块包含一个 [`read`]($app-server#read) 函数，用于从文件系统读取资源，同样只能被服务端运行的代码导入。 ## 您的模块 您可以通过两种方式使您的模块成为仅服务端模块： - 在文件名中添加 `.server`，例如 `secrets.server.js` - 将它们放在 `$lib/server` 中，例如 `$lib/server/secrets.js` ## 工作原理 任何时候，当您有公开的代码，导入仅服务端代码时（无论是直接还是间接）... ```js // @errors: 7005 /// file: $lib/server/secrets.js export const atlantisCoordinates = [ /* 已编辑 */ ]; ``` ```js // @errors: 2307 7006 7005 /// file: src/routes/utils.js export { atlantisCoordinates } from '$lib/server/secrets.js'; export const add = (a, b) => a + b; ``` ```html /// file: src/routes/+page.svelte ``` ...SvelteKit 将报错： ``` Cannot import $lib/server/secrets.js into public-facing code: - src/routes/+page.svelte - src/routes/utils.js - $lib/server/secrets.js ``` 尽管公开代码 — `src/routes/+page.svelte` — 只使用了 `add` 导出而没有使用秘密的 `atlantisCoordinates` 导出，秘密代码也可能最终出现在浏览器下载的 JavaScript 中，因此这个导入链被认为是不安全的。 此功能也适用于动态导入，甚至是像 ``await import(`./${foo}.js`)`` 这样的插值导入，只有一个小注意点：在开发过程中，如果公开代码和仅服务端模块之间存在两个或更多的动态导入，则在第一次加载代码时不会检测到非法导入。 > [!NOTE] 像 Vitest 这样的单元测试框架不区分仅服务端代码和公开代码。因此，当运行测试时，非法导入检测会被禁用，这由 `process.env.TEST === 'true'` 决定。 ## 进一步阅读 - [教程：环境变量](/tutorial/kit/env-static-private) # 快照 临时的 DOM 状态 — 比如侧边栏的滚动位置、`` 元素的内容等 — 在从一个页面导航到另一个页面时会被丢弃。 例如，如果用户填写了一个表单但在提交之前离开并返回，或者用户刷新页面，他们填写的值将会丢失。在需要保留这些输入的情况下，您可以创建一个 DOM 状态的*快照*，当用户返回时可以恢复这个状态。 要实现这一点，从 `+page.svelte` 或 `+layout.svelte` 中导出一个带有 `capture` 和 `restore` 方法的 `snapshot` 对象： ```svelte

评论 <button>发表评论</button> </form> ``` 当您离开这个页面时，`capture` 函数会在页面更新之前立即被调用，返回的值会与浏览器历史栈中的当前记录关联。如果您返回此页面，`restore` 函数会在页面更新后立即被调用，并传入存储的值。 数据必须是可以序列化为 JSON 的，这样它才能被保存到 `sessionStorage` 中。这样就可以在页面重新加载时，或者用户从其他网站返回时恢复状态。 > [!NOTE] 避免从 `capture` 返回非常大的对象 — 一旦被捕获，对象将在会话期间保留在内存中，在极端情况下可能会因太大而无法保存到 `sessionStorage` 中。 # 浅层路由 当您在 SvelteKit 应用中导航时，您会创建*历史记录条目*。点击后退和前进按钮会遍历这个条目列表，重新运行所有 `load` 函数，并在必要时替换页面组件。 有时，在不导航的情况下创建历史条目是有用的。例如，您可能想要显示一个模态对话框，用户可以通过返回导航来关闭它。这在移动设备上特别有价值，因为滑动手势通常比直接与 UI 交互更自然。在这些情况下，*没有*关联历史记录条目的模态可能会令人沮丧，因为用户可能会尝试向后滑动来关闭它，却发现自己到了错误的页面。 SvelteKit 通过 [`pushState`]($app-navigation#pushState) 和 [`replaceState`]($app-navigation#replaceState) 函数使这成为可能，这些函数允许您在不进行导航的情况下将状态与历史记录条目关联。例如，要实现一个由历史驱动的模态： ```svelte <!--- file: +page.svelte ---> <script> import { pushState } from '$app/navigation'; import { page } from '$app/state'; import Modal from './Modal.svelte'; function showModal() { pushState('', { showModal: true }); } </script> {#if page.state.showModal} <Modal close={() => history.back()} /> {/if} ``` 模态框可以通过返回导航（取消设置 `page.state.showModal`）或通过交互触发 `close` 回调运行来关闭。 ## API `pushState` 的第一个参数是相对于当前 URL 的 URL。要保持在当前 URL，使用 `''`。 第二个参数是新的页面状态，可以通过 [page 对象]($app-state#page) 作为 `page.state` 访问。您可以通过声明 [`App.PageState`](types#PageState) 接口（通常在 `src/app.d.ts` 中）来使页面状态类型安全。 要设置页面状态而不创建新的历史记录条目，请使用 `replaceState` 而不是 `pushState`。 > [!旧版说明] > `$app/state` 中的 `page.state` 是在 SvelteKit 2.12 中添加的。如果您使用的是较早版本或正在使用 Svelte 4，请使用 `$app/stores` 中的 `$page.state`。 ## 为路由加载数据 在进行浅层路由时，您可能想在当前页面内渲染另一个 `+page.svelte`。例如，点击照片缩略图可以弹出详细视图，而不需要导航到照片页面。 为此，您需要加载 `+page.svelte` 所需的数据。一个便捷的方法是在 `<a>` 元素的 `click` 处理程序中使用 [`preloadData`]($app-navigation#preloadData)。如果元素（或其父元素）使用 [`data-sveltekit-preload-data`](link-options#data-sveltekit-preload-data)，数据将已经被请求，`preloadData` 将复用该请求。 ```svelte <!--- file: src/routes/photos/+page.svelte ---> <script> import { preloadData, pushState, goto } from '$app/navigation'; import { page } from '$app/state'; import Modal from './Modal.svelte'; import PhotoPage from './[id]/+page.svelte'; let { data } = $props(); </script> {#each data.thumbnails as thumbnail} <a href="/photos/{thumbnail.id}" onclick={async (e) => { if (innerWidth < 640 // 如果屏幕太小则退出 || e.shiftKey // 或链接在新窗口中打开 || e.metaKey || e.ctrlKey // 或新标签页中打开 (mac: metaKey, win/linux: ctrlKey) // 也应考虑鼠标滚轮点击 ) return; // 阻止导航 e.preventDefault(); const { href } = e.currentTarget; // 运行 `load` 函数（或者说，获取由于 `data-sveltekit-preload-data` // 而已经在运行的 `load` 函数的结果） const result = await preloadData(href); if (result.type === 'loaded' && result.status === 200) { pushState(href, { selected: result.data }); } else { // 出现问题！尝试导航 goto(href); } }} > <img alt={thumbnail.alt} src={thumbnail.src} /> </a> {/each} {#if page.state.selected} <Modal onclose={() => history.back()}> <!-- 将页面数据传递给 +page.svelte 组件， 就像 SvelteKit 在导航时那样 --> <PhotoPage data={page.state.selected} /> </Modal> {/if} ``` ## 注意事项 在服务端渲染期间，`page.state` 始终是一个空对象。对于用户首次访问的页面也是如此 — 如果用户重新加载页面（或从另一个文档返回），状态将*不会*应用，直到他们进行导航。 浅层路由是一个需要 JavaScript 才能工作的功能。在使用它时要谨慎，并尝试考虑在 JavaScript 不可用时的合理后备行为。 # Packaging 您可以使用 SvelteKit 来构建应用程序和组件库，使用 `@sveltejs/package` 包（`npx sv create` 提供了设置此功能的选项）。 在创建应用程序时，`src/routes` 的内容是对外公开的部分；[`src/lib`]($lib) 包含应用程序的内部库。 组件库的结构与 SvelteKit 应用程序完全相同，区别在于 `src/lib` 是对外公开的部分，而根目录下的 `package.json` 用于发布包。`src/routes` 可能是随库附带的文档或演示站点，也可能只是开发时使用的沙箱。 运行 `@sveltejs/package` 提供的 `svelte-package` 命令会将 `src/lib` 的内容生成到一个 `dist` 目录中（可以[配置](#Options)），其中包括以下内容： - `src/lib` 中的所有文件。Svelte 组件会被预处理，TypeScript 文件会被转译为 JavaScript。 - 为 Svelte、JavaScript 和 TypeScript 文件生成类型定义（`d.ts` 文件）。您需要安装 `typescript >= 4.0.0` 来支持此功能。类型定义文件会被放置在实现文件旁边，手动编写的 `d.ts` 文件将原样复制。您可以[禁用生成](#Options)，但我们强烈建议不要这样做 —— 使用您库的用户可能会需要这些文件来支持 TypeScript。 > [!注意] `@sveltejs/package` 的第 1 版会生成一个 `package.json`。现在不再如此，它会使用项目中的 `package.json` 并验证其正确性。如果您仍然使用第 1 版，请查看[此 PR](https://github.com/sveltejs/kit/pull/8922) 获取迁移说明。 ## `package.json` 的结构 因为您现在正在为公共使用构建一个库，因此 `package.json` 的内容变得更为重要。通过它，您可以配置包的入口点、发布到 npm 的文件以及库的依赖。我们将逐一介绍最重要的字段。 ### name 这是您包的名称，其他人可以使用该名称安装您的包，并可在 `https://npmjs.com/package/<name>` 网站上看到它。 ```json { "name": "your-library" } ``` 在[此处](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#name)阅读关于它的更多内容。 ### license 每个包都应有一个 license 字段，以告知人们如何使用它。目前非常流行的一种许可证是 `MIT`，它在分发和复用方面非常宽松且无需担保。 ```json { "license": "MIT" } ``` 在[此处](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#license)阅读关于它的更多内容。请注意，应在包中包含一个 `LICENSE` 文件。 ### files 该字段告诉 npm 哪些文件将被打包并上传到 npm。它应包含输出文件夹（默认为 `dist`）。您的 `package.json`、`README` 和 `LICENSE` 文件会始终被包括在内，因此您不需要指定它们。 ```json { "files": ["dist"] } ``` 要排除不必要的文件（如单元测试，或者仅从 `src/routes` 导入的模块等）可以将它们添加到 `.npmignore` 文件中。这将导致包更小，安装速度更快。 在[此处](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#files)阅读关于它的更多内容。 ### exports `"exports"` 字段包含包的入口点。如果您通过 `npx sv create` 设置了一个新的库项目，它会设置为单一出口，即包的根目录： ```json { "exports": { ".": { "types": "./dist/index.d.ts", "svelte": "./dist/index.js" } } } ``` 这告诉打包工具和工具链，您的包只有一个入口点，即根目录，所有内容应通过以下方式导入： ```js // @errors: 2307 import { Something } from 'your-library'; ``` `types` 和 `svelte` 键是[导出条件](https://nodejs.org/api/packages.html#conditional-exports)，它们告诉工具在查找 `your-library` 导入时应引入哪个文件： - TypeScript 看到 `types` 条件，会查找类型定义文件。如果您不发布类型定义，请忽略此条件。 - 支持 Svelte 的工具会看到 `svelte` 条件，知道这是一个 Svelte 组件库。如果您发布的库不导出任何 Svelte 组件,并且也可以在非 Svelte 项目中使用（如 Svelte store 库），您可以将此条件替换为 `default`。 > [!注意] 早期版本的 `@sveltejs/package` 还添加了一个 `package.json` 导出。这不再是模板的一部分，因为所有工具都可以处理没有明确导出的 `package.json`。 您可以根据需要调整 `exports` 并提供更多入口点。例如，如果您想直接暴露 `src/lib/Foo.svelte` 组件而不是通过 `src/lib/index.js` 文件重新导出组件，您可以创建以下导出映射…… ```json { "exports": { "./Foo.svelte": { "types": "./dist/Foo.svelte.d.ts", "svelte": "./dist/Foo.svelte" } } } ``` ……然后您的库的使用者可以用如下方式导入该组件： ```js // @filename: ambient.d.ts declare module 'your-library/Foo.svelte'; // @filename: index.js // ---cut--- import Foo from 'your-library/Foo.svelte'; ``` > [!注意] 请注意，如果您提供类型定义，采用此方式可能需要额外处理。在[此处](#TypeScript)阅读关于此问题的更多详细信息。 通常，`exports` 映射的每个键都是用户从您的包中导入某些内容的路径。而值则是将被导入的文件的路径或包含这些文件路径的导出条件映射。 在[此处](https://nodejs.org/docs/latest-v18.x/api/packages.html#package-entry-points)阅读关于 `exports` 的更多内容。 ### svelte 这是一个遗留字段，用于让工具识别 Svelte 组件库。如果使用 `svelte` [导出条件](#Anatomy-of-a-package.json-exports)，它已不再必要，但为了向尚未了解导出条件的过时工具提供兼容性，建议保留它。它应指向您的根入口点。 ```json { "svelte": "./dist/index.js" } ``` ### sideEffects `package.json` 中的 `sideEffects` 字段用于让打包工具判断模块是否可能包含副作用。如果模块在被导入时对其他脚本可见的行为产生变化（例如修改全局变量或内置 JavaScript 对象的原型），则视为有副作用。由于副作用可能会影响应用程序的其他部分，这些文件/模块无论其导出是否在应用程序中使用，都会被包括在最终的打包文件中。 在 `sideEffects` 字段中指定的模块会帮助打包工具更积极地从最终的打包文件中剔除未使用的导出（即 tree-shaking），从而生成更小更高效的打包文件。不同的打包工具以不同的方式处理 `sideEffects`。尽管 Vite 不需要此配置，但建议为库声明所有 CSS 文件具有副作用，以保持与 [webpack](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free) 兼容。新创建的项目中的默认配置如下： ```json /// file: package.json { "sideEffects": ["**/*.css"] } ``` > 如果您的库中的脚本存在副作用，请确保更新 `sideEffects` 字段。在新创建的项目中，所有脚本默认标记为无副作用。如果错误地将包含副作用的文件标记为没有副作用，可能会导致功能异常。 如果您的包中有副作用的文件，可以通过数组指定这些文件： ```json /// file: package.json { "sideEffects": ["**/*.css", "./dist/sideEffectfulFile.js"] } ``` 这样只会将指定的文件视为有副作用的文件。 ## TypeScript 即使您自己不使用 TypeScript，也应为您的库提供类型定义，这样使用您库的人可以获得正确的智能提示。`@sveltejs/package` 让生成类型的过程对您来说基本上是透明的。默认情况下，在打包您的库时，会为 JavaScript、TypeScript 和 Svelte 文件自动生成类型定义。您只需要确保 [exports](#Anatomy-of-a-package.json-exports) 映射中的 `types` 条件指向正确的文件。当通过 `npx sv create` 初始化库项目时，会自动设置为根导出。 然而，如果您除了根导出还有其他内容，例如提供 `your-library/foo` 导入，您需要额外注意提供类型定义。不幸的是，默认情况下 TypeScript _不会_ 为这种导出解析 `types` 条件，比如 `{ "./foo": { "types": "./dist/foo.d.ts", ... }}`。相反，它会从库的根目录（即 `your-library/foo.d.ts` 而不是 `your-library/dist/foo.d.ts`）查找 `foo.d.ts` 文件。为了解决这个问题，您有两种选择： 第一种选择是要求使用您库的人在其 `tsconfig.json`（或 `jsconfig.json`）中将 `moduleResolution` 选项设置为 `bundler`（从 TypeScript 5 开始可用，未来是最佳推荐选项）、`node16` 或 `nodenext`。这会使 TypeScript 实际查看 exports 映射并正确解析这些类型。 第二种选择是滥用 TypeScript 的 `typesVersions` 特性连接类型。`typesVersions` 是 `package.json` 中的一个字段，TypeScript 根据 TypeScript 版本检查不同类型定义，同时也包含路径映射功能。我们利用该路径映射功能来满足需求。对于上面提到的 `foo` 导出，相应的 `typesVersions` 定义如下： ```json { "exports": { "./foo": { "types": "./dist/foo.d.ts", "svelte": "./dist/foo.js" } }, "typesVersions": { ">4.0": { "foo": ["./dist/foo.d.ts"] } } } ``` `>4.0` 表示如果使用的 TypeScript 版本大于 4，则 TypeScript 会检查内部映射。内部映射告诉 TypeScript `your-library/foo` 的类型定义在 `./dist/foo.d.ts` 中，这实际上是对 `exports` 条件的复制。您还可以使用 `*` 通配符一次性提供多个类型定义而无需重复。如果选择使用 `typesVersions`，您需要通过它声明所有类型导入，包括根导入（定义为 `"index.d.ts": [..]`）。 您可以在[此处](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#version-selection-with-typesversions) 阅读有关该功能的更多信息。 ## 最佳实践 除非您计划将包仅供其他 SvelteKit 项目使用，否则应避免在包中使用 SvelteKit 特定模块（如 `$app/environment`）。例如，与其使用 `import { browser } from '$app/environment'`，不如使用 `import { BROWSER } from 'esm-env'`（[参见 esm-env 文档](https://github.com/benmccann/esm-env)）。您可能还希望将当前 URL 或导航操作作为 prop 传入，而不是直接依赖 `$app/state`、`$app/navigation` 等。这种更通用的编写方式还会使测试、UI 演示等工具的设置变得更加容易。 在 `svelte.config.js`（而非 `vite.config.js` 或 `tsconfig.json`）中通过 [aliases](configuration#alias) 添加别名，以便它们被 `svelte-package` 处理。 应仔细考虑对包的更改是错误修复、新功能还是重大更改，并相应地更新包版本。注意，如果从现有库中移除任何 `exports` 路径或其内的任何 `export` 条件，应将其视为重大更改。 ```json { "exports": { ".": { "types": "./dist/index.d.ts", // 将 `svelte` 更改为 `default` 是重大更改： --- "svelte": "./dist/index.js"--- +++ "default": "./dist/index.js"+++ }, // 移除此项是重大更改： --- "./foo": { "types": "./dist/foo.d.ts", "svelte": "./dist/foo.js", "default": "./dist/foo.js" },--- // 添加此项是可以的： +++ "./bar": { "types": "./dist/bar.d.ts", "svelte": "./dist/bar.js", "default": "./dist/bar.js" }+++ } } ``` ## 选项 `svelte-package` 接受以下选项： - `-w`/`--watch` — 监听 `src/lib` 的文件更改并重新构建包 - `-i`/`--input` — 包含包所有文件的输入目录。默认为 `src/lib` - `-o`/`--output` — 处理后的文件写入的输出目录。您的 `package.json` 的 `exports` 应指向该文件夹内的文件，`files` 数组也应包含该文件夹。默认为 `dist` - `-t`/`--types` — 是否创建类型定义（`d.ts` 文件）。我们强烈建议这样做，因为它有助于提升生态系统库的质量。默认为 `true` - `--tsconfig` — tsconfig 或 jsconfig 的路径。如果未提供，则会在工作区路径中搜索最近的 tsconfig/jsconfig。 ## 发布 要发布生成的包： ```sh npm publish ``` ## 限制 所有的相对文件导入需要完全指定路径，遵守 Node 的 ESM 算法。这意味着对于像 `src/lib/something/index.js` 这样的文件，必须包括文件名和扩展名： ```js // @errors: 2307 import { something } from './something+++/index.js+++'; ``` 如果您使用 TypeScript，您需要以同样的方式导入 `.ts` 文件，但使用 `.js` 文件后缀而不是 `.ts` 文件后缀。（这是一个 TypeScript 的设计决策，超出我们的控制范围。）在您的 `tsconfig.json` 或 `jsconfig.json` 中设置 `"moduleResolution": "NodeNext"` 将有助于解决这个问题。 除 Svelte 文件（预处理）和 TypeScript 文件（转换为 JavaScript）外，所有文件都按原样复制。 # 身份认证 身份认证（Auth）指的是认证（authentication）和授权（authorization），这是构建 Web 应用程序时的常见需求。认证是指根据用户提供的凭证验证用户的身份。授权是指确定用户被允许执行哪些操作。 ## 会话（Sessions） vs 令牌（tokens） 在用户提供了用户名和密码等凭证后，我们希望允许他们使用应用程序，而无需在后续请求中再次提供凭证。用户在随后的请求中通常通过会话标识符（session identifier）或签名令牌（如 JSON Web Token，JWT）进行认证。 会话 ID 最常被存储在数据库中。它们可以被立即撤销，但每次请求都需要进行数据库查询。 相比之下，JWT 通常不会与数据存储进行校验，这意味着它们无法被立即撤销。这种方法的优势是改善了延迟并减少了数据存储的负载。 ## 集成点 可以在[服务端 hooks](hooks#Server-hooks)中检查身份认证 [cookies](@sveltejs-kit#Cookies)。如果找到与提供的凭证匹配的用户，用户信息可以存储在 [`locals`](hooks#Server-hooks-handle) 中。 ## 指南 [Lucia](https://lucia-auth.com/)是一个基于会话的 Web 应用程序认证的参考。它包含了在 SvelteKit 和其他 JS 项目中实现基于会话认证的示例代码片段和项目。您可以在创建新项目时使用 `npx sv create` 或在现有项目中使用 `npx sv add lucia` 来添加遵循 Lucia 指南的代码。 身份认证系统与 web 框架紧密耦合，因为大部分代码都在验证用户输入、处理错误和引导用户到适当的下一页。因此，许多通用的 JS 认证库都包含了一个或多个 web 框架。基于这个原因，许多用户会发现遵循 SvelteKit 特定的指南（如在[Lucia](https://lucia-auth.com/)中找到的示例）比在项目中包含多个 web 框架更可取。 # 性能 SvelteKit 开箱即用地做了很多工作来使您的应用程序尽可能高效： - 代码分割，因此只加载当前页面所需的代码 - 资源预加载，防止出现"瀑布（waterfalls）"（文件请求其他文件的情况） - 文件哈希，使您的资源可以永久缓存 - 请求合并，将从不同服务端 `load` 函数获取的数据合并成单个 HTTP 请求 - 并行加载，不同的通用 `load` 函数同时获取数据 - 数据内联，服务端渲染期间使用 `fetch` 发出的请求可以在浏览器中重放而无需重新发出请求 - 保守的失效处理，因此 `load` 函数仅在必要时重新运行 - 预渲染（如有必要，可按路由配置），使没有动态数据的页面可以立即提供服务 - 链接预加载，以便提前主动获取客户端导航所需的数据和代码 尽管如此，我们（尚）不能消除所有导致性能下降的因素。要获得最大性能，您应该注意以下建议。 ## 诊断问题 Google 的 [PageSpeed Insights](https://pagespeed.web.dev/) 和（用于更高级分析的）[WebPageTest](https://www.webpagetest.org/) 是了解已部署到互联网的网站性能特征的出色工具。 您的浏览器还包含有用的开发者工具，用于分析您的网站，无论是已部署还是在本地运行： - Chrome - [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview#devtools)、[Network](https://developer.chrome.com/docs/devtools/network) 和 [Performance](https://developer.chrome.com/docs/devtools/performance) 开发工具 - Edge - [Lighthouse](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/lighthouse/lighthouse-tool)、[Network](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/) 和 [Performance](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/evaluate-performance/) 开发工具 - Firefox - [Network](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/) 和 [Performance](https://hacks.mozilla.org/2022/03/performance-tool-in-firefox-devtools-reloaded/) 开发工具 - Safari - [提升网页性能](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/Web_Inspector_Tutorial/EnhancingyourWebpagesPerformance/EnhancingyourWebpagesPerformance.html) 请注意，在 `dev` 模式下本地运行的网站会表现出与生产应用程序不同的行为，因此您应该在构建后在[预览](building-your-app#Preview-your-app)模式下进行性能测试。 ### 检测 如果您在浏览器的网络标签中看到 API 调用耗时过长，想了解原因，您可以考虑使用 [OpenTelemetry](https://opentelemetry.io/) 或 [Server-Timing 头](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing) 等工具来检测您的后端。 ## 优化资源 ### 图片 减小图片文件的大小通常是对网站性能影响最大的改变之一。Svelte 提供了 `@sveltejs/enhanced-img` 包，详见[图片](images)页面，可以让这个过程更容易。此外，Lighthouse 对识别性能影响最大的图片很有帮助。 ### 视频 视频文件可能非常大，因此应特别注意确保它们经过优化： - 使用 [Handbrake](https://handbrake.fr/) 等工具压缩视频。考虑将视频转换为 `.webm` 或 `.mp4` 等 web 友好的格式。 - 您可以使用 `preload="none"` 对折叠区域以下的视频进行[延迟加载](https://web.dev/articles/lazy-loading-video)（但请注意，这会在用户开始播放时减慢播放速度）。 - 使用 [FFmpeg](https://ffmpeg.org/) 等工具从静音视频中删除音轨。 ### 字体 当用户访问页面时，SvelteKit 会自动预加载关键的 `.js` 和 `.css` 文件，但默认情况下不会预加载字体，因为这可能会导致下载不必要的文件（例如 CSS 中引用但实际上在当前页面上未使用的字体粗细）。话虽如此，正确预加载字体可以对网站的速度感知产生很大影响。在您的 [`handle`](hooks#Server-hooks-handle) hook 中，您可以使用包含字体的 `preload` 过滤器调用 `resolve`。 通过[子集化](https://web.dev/learn/performance/optimize-web-fonts#subset_your_web_fonts)字体，您可以减小字体文件的大小。 ## 减少代码大小 ### Svelte 版本 我们推荐使用最新版本的 Svelte。Svelte 5 比 Svelte 4 更小更快，而 Svelte 4 又比 Svelte 3 更小更快。 ### 包 [`rollup-plugin-visualizer`](https://www.npmjs.com/package/rollup-plugin-visualizer) 可以帮助识别哪些包对网站大小贡献最大。您还可以通过手动检查构建输出发现删除代码的机会（在您的 [Vite 配置](https://vitejs.dev/config/build-options.html#build-minify)中使用 `build: { minify: false }` 使输出可读，但记得在部署应用程序之前撤销此更改），或通过浏览器开发工具的网络标签。 ### 外部脚本 尽量减少在浏览器中运行的第三方脚本数量。例如，与其使用基于 JavaScript 的分析工具，不如考虑使用服务端实现，比如许多带有 SvelteKit 适配器的平台，包括 [Cloudflare](https://www.cloudflare.com/web-analytics/)、[Netlify](https://docs.netlify.com/monitor-sites/site-analytics/) 和 [Vercel](https://vercel.com/docs/analytics) 所提供的解决方案。 要在 Web Worker 中运行第三方脚本（避免阻塞主线程），请使用 [Partytown 的 SvelteKit 集成](https://partytown.builder.io/sveltekit)。 ### 选择性加载 使用静态 `import` 声明导入的代码将自动与页面的其余部分打包在一起。如果某段代码仅在满足特定条件时才需要，请使用动态 `import(...)` 形式来选择性地延迟加载组件。 ## 导航 ### 预加载 您可以使用[链接选项](link-options)预先加载必要的代码和数据来加快客户端导航。当您创建新的 SvelteKit 应用程序时，`<body>` 元素上是默认有配置的。 ### 非必要数据 对于加载缓慢且不需要立即使用的数据，从 `load` 函数返回的对象可以包含 promise 而不是数据本身。对于服务端 `load` 函数，这将导致数据在导航（或初始页面加载）后[流式传输](load#Streaming-with-promises)。 ### 防止瀑布问题 最大的性能杀手之一是所谓的瀑布问题，即一系列按顺序发出的请求。这可能发生在服务端或浏览器中。 - 当您的 HTML 请求 JS，然后请求 CSS，然后请求背景图片和网络字体时，可能会在浏览器中出现资源瀑布。SvelteKit 通过添加 [`modulepreload`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/modulepreload) 标签或头部，将为您解决这类问题，但您应该查看[开发工具中的网络标签](#Diagnosing-issues)以检查是否需要预加载其他资源。如果您使用网络[字体](#Optimizing-assets-Fonts)，请特别注意这一点，因为它们需要手动处理。 - 如果通用 `load` 函数发起 API 调用来获取当前用户，然后使用该响应中的详细信息来获取已保存项目的列表，然后使用该响应来获取每个项目的详细信息，浏览器最终将发出多个顺序请求。这对性能来说是致命的，尤其是对于物理位置远离您后端的用户。在可能的情况下使用[服务端 `load` 函数](load#Universal-vs-server)来避免这个问题。 - 服务端 `load` 函数也不能免疫瀑布问题（尽管它们的代价要小得多，因为它们很少涉及高延迟的往返）。例如，如果您查询数据库以获取当前用户，然后使用该数据进行第二次查询以获取已保存项目的列表，使用带有数据库连接的单个查询通常会更高效。 ## 托管 为了最小化延迟，你的前端应该与后端位于同一数据中心。对于没有中央后端的站点，许多 SvelteKit 适配器支持部署到 edge，这意味着从离用户最近的服务器处理每个用户的请求。这可以显著减少加载时间。一些适配器甚至支持[按路由配置部署](page-options#config)。您还应该考虑从 CDN（通常是 edge 网络）提供图片服务 — 许多 SvelteKit 适配器的主机会自动完成这项工作。 确保您的主机使用 HTTP/2 或更新版本。Vite 的代码分割创建了许多小文件以提高缓存能力，这会带来出色的性能表现，但这建立在您的文件可以通过 HTTP/2 并行加载的前提下。 ## 延伸阅读 在大多数情况下，构建高性能的 SvelteKit 应用程序与构建任何高性能的 Web 应用程序是一样的。您应该能够将这些来自通用性能资源（如 [Core Web Vitals](https://web.dev/explore/learn-core-web-vitals)）的信息应用到任何您构建的 Web 体验中。 # 图片 图片会对您的应用性能产生重大影响。为了获得最佳效果，您应该通过以下方式优化它们： - 生成最优格式如 `.avif` 和 `.webp` - 为不同的屏幕创建不同尺寸的图片 - 确保资源可以被有效缓存 手动完成这些工作很繁琐。根据您的需求和偏好，您可以使用多种技术。 ## Vite 的内置处理 [Vite 会自动处理导入的资源](https://vitejs.dev/guide/assets.html)以提升性能。这包括通过 CSS `url()` 函数引用的资源。文件名中会添加哈希值以便缓存，小于 `assetsInlineLimit` 的资源会被内联。Vite 的资源处理最常用于图片，但对视频、音频等也很有用。 ```svelte <script> import logo from '$lib/assets/logo.png'; </script> <img alt="项目标志" src={logo} /> ``` ## @sveltejs/enhanced-img `@sveltejs/enhanced-img` 是在 Vite 内置资源处理基础上提供的插件。它提供即插即用的图片处理功能，可以提供更小的文件格式如 `avif` 或 `webp`，自动设置图片的固有 `width` 和 `height` 以避免布局偏移，为各种设备创建多种尺寸的图片，并出于隐私考虑去除 EXIF 数据。它可以在任何基于 Vite 的项目中使用，包括但不限于 SvelteKit 项目。 > [!NOTE] 作为构建插件，`@sveltejs/enhanced-img` 只能在构建过程中优化位于您机器上的文件。如果您的图片位于其他位置（如从数据库、CMS 或后端服务的路径），请阅读[从 CDN 动态加载图片](#Loading-images-dynamically-from-a-CDN)。 > > **警告**：`@sveltejs/enhanced-img` 包是实验性的。它使用 1.0 之前的版本号，每个小版本发布可能会引入破坏性变更。 ### 设置 安装： ```bash npm install --save-dev @sveltejs/enhanced-img ``` 调整 `vite.config.js`： ```js import { sveltekit } from '@sveltejs/kit/vite'; +++import { enhancedImages } from '@sveltejs/enhanced-img';+++ import { defineConfig } from 'vite'; export default defineConfig({ plugins: [ +++enhancedImages(),+++ sveltekit() ] }); ``` 由于转换图片的计算开销，第一次构建会花费更长时间。但是，构建输出会被缓存在 `./node_modules/.cache/imagetools` 中，因此后续的构建会很快。 ### 基本用法 在你的 `.svelte` 组件中使用 `<enhanced:img>` 而不是`<img>`，并通过 [Vite 资源导入](https://vitejs.dev/guide/assets.html#static-asset-handling) 路径引用图片文件： ```svelte <enhanced:img src="./path/to/your/image.jpg" alt="An alt text" /> ``` 在构建时，您的 `<enhanced:img>` 标签将被 `<img>` 替换，并由 `<picture>` 包装，提供多种图片类型和尺寸。在不损失质量的情况下只能对图片进行缩小，这意味着你应该提供所需的最高分辨率图片——系统会为可能请求图片的各种设备类型生成较小的版本。 你应该为 HiDPI 显示器（又称视网膜显示器）提供 2x 分辨率的图片。`<enhanced:img>` 会自动负责向较小的设备提供较小版本的图片。 如果你想为 `<enhanced:img>` 添加样式，你应该添加一个 `class` 并针对它进行设置。 ### 动态选择图像 您也可以手动导入图片资源并将其传递给 `<enhanced:img>`。当您有一组静态图片并想要动态选择或[遍历它们](https://github.com/sveltejs/kit/blob/0ab1733e394b6310895a1d3bf0f126ce34531170/sites/kit.svelte.dev/src/routes/home/Showcase.svelte)时，这种方法很有用。在这种情况下，您需要同时更新 `import` 语句和 `<img>` 元素，如下所示，以表明您想要处理它们。 ```svelte <script> import MyImage from './path/to/your/image.jpg?enhanced'; </script> <enhanced:img src={MyImage} alt="some alt text" /> ``` 你也可以使用 Vite 的 [import.meta.glob](https://vitejs.dev/guide/features.html#glob-import)。请注意，你需要通过[自定义查询](https://vitejs.dev/guide/features.html#custom-queries)来指定 `enhanced`： ```svelte <script> const imageModules = import.meta.glob( '/path/to/assets/*.{avif,gif,heif,jpeg,jpg,png,tiff,webp,svg}', { eager: true, query: { enhanced: true } } ) </script> {#each Object.entries(imageModules) as [_path, module]} <enhanced:img src={module.default} alt="some alt text" /> {/each} ``` ### 固有尺寸 `width` 和 `height` 是可选的，因为它们可以从源图像中推断出来，并且在预处理 `<enhanced:img>` 标签时会自动添加。有了这些属性，浏览器可以保留正确的空间，防止[布局偏移](https://web.dev/articles/cls)。 如果你想使用不同的 `width` 和 `height`，你可以用 CSS 来设置图像样式。由于预处理器会为你添加 `width` 和 `height`，如果你想要其中一个尺寸自动计算，那么你需要指定这一点： ```svelte <style> .hero-image img { width: var(--size); height: auto; } </style> ``` ### `srcset` 和 `sizes` 如果你有一个大图像，比如占据设计宽度的主图，你应该指定 `sizes`，这样在较小的设备上就会请求较小版本的图像。例如，如果你有一个 1280px 的图像，你可能想要指定类似这样的内容： ```svelte <enhanced:img src="./image.png" sizes="min(1280px, 100vw)"/> ``` 如果指定了 `sizes`，`<enhanced:img>` 将为较小的设备生成小尺寸图片，并填充 `srcset` 属性。 自动生成的最小图片宽度为 540px。如果你需要更小的图片或想要指定自定义宽度，可以使用 `w` 查询参数： ```svelte <enhanced:img src="./image.png?w=1280;640;400" sizes="(min-width:1920px) 1280px, (min-width:1080px) 640px, (min-width:768px) 400px" /> ``` 如果未提供 `sizes`，则将生成一个 HiDPI/Retina 图像和一个标准分辨率图像。您提供的图像应该是您希望显示分辨率的 2 倍，以便浏览器可以在具有[高设备像素比](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio)的设备上显示该图像。 ### 每个图像的转换 默认情况下，增强的图像将被转换为更高效的格式。但是，你可能希望应用其他转换，如模糊、质量调整、扁平化或旋转操作。你可以通过附加查询字符串来执行每个图像的转换： ```svelte <enhanced:img src="./path/to/your/image.jpg?blur=15" alt="An alt text" /> ``` [查看 imagetools 仓库以获取完整的指令列表。](https://github.com/JonasKruckenberg/imagetools/blob/main/docs/directives.md). ## 从 CDN 动态加载图片 在某些情况下，图片在构建时可能无法访问 —— 例如，它们可能存储在内容管理系统或其他地方。 使用内容分发网络（CDN）可以让你动态优化这些图片，并在尺寸方面提供更多灵活性，但可能需要一些设置开销和使用成本。根据缓存策略，在从 CDN 收到 [304 响应](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304)之前，浏览器可能无法使用资源的缓存副本。构建面向 CDN 的 HTML 允许使用 `<img>` 标签，因为 CDN 可以根据 `User-Agent` 头部提供适当的格式，而构建时优化必须生成带有多个源的 `<picture>` 标签。最后，某些 CDN 可能会延迟生成图片，这可能会对低流量且图片频繁更改的网站的性能产生负面影响。 CDN 通常可以直接使用，无需任何库。然而，有许多支持 Svelte 的库可以让使用变得更简单。[`@unpic/svelte`](https://unpic.pics/img/svelte/) 是一个支持大量提供商的与 CDN 无关的库。你可能还会发现一些特定的 CDN（如 [Cloudinary](https://svelte.cloudinary.dev/)）有 Svelte 支持。最后，一些支持 Svelte 的内容管理系统（CMS）（如 [Contentful](https://www.contentful.com/sveltekit-starter-guide/)、[Storyblok](https://github.com/storyblok/storyblok-svelte) 和 [Contentstack](https://www.contentstack.com/docs/developers/sample-apps/build-a-starter-website-with-sveltekit-and-contentstack) 都内置了图像处理支持。 ## 最佳实践 - 对于每种图片类型，使用上述讨论过的适当解决方案。你可以在一个项目中混合使用这三种解决方案。例如，你可以使用 Vite 的内置处理来为 `<meta>` 标签提供图片，使用 `@sveltejs/enhanced-img` 在主页上显示图片，并使用动态方法显示用户提交的内容。 - 考虑通过 CDN 提供所有图片服务，无论你使用何种图片优化类型。CDN 通过在全球分发静态资源副本来减少延迟。 - 原始图片应具有良好的质量/分辨率，并且宽度应该是显示宽度的 2 倍，以便支持 HiDPI 设备。图片处理可以将图片尺寸缩小以在服务较小屏幕时节省带宽，但为了放大图片而创造像素会浪费带宽。 - 对于远大于移动设备宽度（大约400px）的图片，例如占据页面设计宽度的主图，指定 `sizes` 以便在较小设备上提供较小的图片。 - 对于重要图片，例如[最大内容绘制（LCP）](https://web.dev/articles/lcp)图片，设置 `fetchpriority="high" loading="eager"` 以尽早优先加载。 - 为图片提供容器或样式，使其受到约束，不会在页面加载时跳动影响[累积布局偏移（CLS）](https://web.dev/articles/cls)。`width` 和 `height` 帮助浏览器在图片仍在加载时预留空间，因此 `@sveltejs/enhanced-img` 将为你添加 `width` 和 `height`。 - 始终提供良好的 `alt` 文本。如果你没有这样做，Svelte编译器会发出警告。 - 不要在 `sizes` 中使用 `em` 或 `rem` 并更改这些度量的默认大小。当在 `sizes` 或 `@media` 查询中使用时，`em` 和 `rem` 都被定义为用户的默认 `font-size`。对于像 `sizes="(min-width: 768px) min(100vw, 108rem), 64rem"` 这样的 `sizes` 声明，控制图片在页面上布局方式的实际 `em` 或 `rem` 如果被 CSS 更改可能会有所不同。例如，不要做类似 `html { font-size: 62.5%; }` 这样的事情，因为浏览器预加载器预留的空间现在会比创建后的 CSS 对象模型的实际空间更大。 # 无障碍 SvelteKit 默认努力为您的应用程序提供一个无障碍的平台。Svelte 的[编译时无障碍检查](../svelte/compiler-warnings)也将适用于您构建的任何 SvelteKit 应用程序。 以下是 SvelteKit 内置无障碍功能的工作原理，以及您需要做什么来帮助这些功能尽可能好地工作。请记住，虽然 SvelteKit 提供了无障碍的基础，但您仍然要负责确保您的应用程序代码是无障碍的。如果您是无障碍新手，请参阅本指南的["进一步阅读"](accessibility#Further-reading)部分获取更多资源。 我们认识到实现无障碍可能很困难。如果您想就 SvelteKit 处理无障碍的方式提出改进建议，请[提交 GitHub issue](https://github.com/sveltejs/kit/issues)。 ## 路由公告 在传统的服务端渲染应用程序中，每次导航（例如点击 `<a>` 标签）都会触发完整的页面重载。当这种情况发生时，屏幕阅读器和其他辅助技术会读出新页面的标题，让用户理解页面已经改变。 由于 SvelteKit 中页面之间的导航无需重新加载页面（称为[客户端路由](glossary#Routing)），SvelteKit 在页面上注入了一个[实时区域](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)，在每次导航后读出新页面名称。它通过检查 `<title>` 元素来确定要宣布的页面名称。 因此，您应用程序中的每个页面都应该有一个独特的、描述性的标题。在 SvelteKit 中，您可以通过在每个页面上放置 `<svelte:head>` 元素来实现： ```svelte <!--- file: src/routes/+page.svelte ---> <svelte:head> <title>待办事项列表</title> </svelte:head> ``` 这将使屏幕阅读器和其他辅助技术能够在导航发生后识别新页面。提供描述性标题对于 [SEO](seo#Manual-setup-title-and-meta) 也很重要。 ## 焦点管理 在传统的服务端渲染应用程序中，每次导航都会将焦点重置到页面顶部。这确保了使用键盘或屏幕阅读器浏览网页的人可以从页面开始处开始交互。 为了在客户端路由期间模拟这种行为，SvelteKit 在每次导航和[增强型表单提交](form-actions#Progressive-enhancement)后会将焦点设置在 `<body>` 元素上。有一个例外 - 如果存在带有 [`autofocus`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) 属性的元素，SvelteKit 将转而聚焦该元素。使用该属性时，请确保[考虑对辅助技术的影响](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus#accessibility_considerations)。 如果您想自定义 SvelteKit 的焦点管理，可以使用 `afterNavigate` 钩子： ```js /// <reference types="@sveltejs/kit" /> // ---cut--- import { afterNavigate } from '$app/navigation'; afterNavigate(() => { /** @type {HTMLElement | null} */ const to_focus = document.querySelector('.focus-me'); to_focus?.focus(); }); ``` 您也可以使用 [`goto`]($app-navigation#goto) 函数以编程方式导航到不同的页面。默认情况下，这将具有与点击链接相同的客户端路由行为。但是，`goto` 也接受一个 `keepFocus` 选项，该选项将保留当前聚焦的元素，而不是重置焦点。如果启用此选项，请确保当前聚焦的元素在导航后仍然存在于页面上。如果该元素不再存在，用户的焦点将丢失，这会让辅助技术用户感到困惑。 ## "lang" 属性 默认情况下，SvelteKit 的页面模板将文档的默认语言设置为英语。如果您的内容不是英语，您应该更新 `src/app.html` 中的 `<html>` 元素，使其具有正确的 [`lang`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#accessibility) 属性。这将确保任何阅读文档的辅助技术使用正确的发音。例如，如果您的内容是德语，您应该将 `app.html` 更新为： ```html /// file: src/app.html <html lang="de"></html> ``` 如果您的内容提供多种语言，您应该根据当前页面的语言设置 `lang` 属性。您可以使用 SvelteKit 的 [handle hook](hooks#Server-hooks-handle)来实现： ```html /// file: src/app.html <html lang="%lang%"></html> ``` ```js /// file: src/hooks.server.js /** * @param {import('@sveltejs/kit').RequestEvent} event */ function get_lang(event) { return 'en'; } // ---cut--- /** @type {import('@sveltejs/kit').Handle} */ export function handle({ event, resolve }) { return resolve(event, { transformPageChunk: ({ html }) => html.replace('%lang%', get_lang(event)) }); } ``` ## 进一步阅读 在大多数情况下，构建无障碍 SvelteKit 应用程序与构建无障碍 Web 应用程序是一样的。您应该能够将以下通用无障碍资源中的信息应用到您构建的任何 Web 体验中： - [MDN Web 文档：无障碍](https://developer.mozilla.org/en-US/docs/Learn/Accessibility) - [A11y 项目](https://www.a11yproject.com/) - [如何满足 WCAG（快速参考）](https://www.w3.org/WAI/WCAG21/quickref/) # SEO SEO 最重要的方面是创建高质量的内容，使其能在网络上被广泛链接。但是，构建能够良好排名的网站，还需要考虑一些技术因素。 ## 开箱即用的功能 ### SSR（服务端渲染） 虽然近年来搜索引擎在索引客户端 JavaScript 渲染的内容方面有所改善，但服务端渲染的内容仍然能够更频繁和可靠地被索引。SvelteKit 默认采用 SSR，虽然您可以在[`handle`](hooks#Server-hooks-handle)中禁用它，但除非有充分的理由，否则应该保持启用。 > [!NOTE] SvelteKit 的渲染是高度可配置的，您可以根据需要实现[动态渲染](https://developers.google.com/search/docs/advanced/javascript/dynamic-rendering)。但这通常不推荐，因为 SSR 除了 SEO 之外还有其他好处。 ### 性能 [核心网页指标](https://web.dev/vitals/#core-web-vitals)等信号会影响搜索引擎排名。由于 Svelte 和 SvelteKit 引入的开销最小，因此更容易构建高性能网站。您可以使用 Google 的 [PageSpeed Insights](https://pagespeed.web.dev/) 或 [Lighthouse](https://developers.google.com/web/tools/lighthouse) 测试您的网站性能。详情请阅读[性能页面](performance)。 ### URL 标准化 SvelteKit 会将带有尾部斜杠的路径重定向到不带斜杠的路径（或根据您的[配置](page-options#trailingSlash)反向操作），因为重复的 URL 对 SEO 不利。 ## 手动设置 ### `<title>` 和 `<meta>` 每个页面都应该在 [`<svelte:head>`](../svelte/svelte-head) 中包含精心编写的独特的 `<title>` 和 `<meta name="description">` 元素。关于如何编写描述性标题和描述，以及其他使内容便于搜索引擎理解的建议，可以在Google的 [Lighthouse SEO 审核](https://web.dev/lighthouse-seo/) 文档中找到。 > [!NOTE] 一个常见的模式是从页面的 [`load`](load) 函数返回与 SEO 相关的 `data`，然后在根[布局](routing#layout)的 `<svelte:head>` 中使用它（作为[`page.data`]($app-state)）。 ### 站点地图 [站点地图](https://developers.google.com/search/docs/advanced/sitemaps/build-sitemap)可帮助搜索引擎对网站内的页面进行优先级排序，特别是当您有大量内容时。您可以使用端点动态创建站点地图： ```js /// file: src/routes/sitemap.xml/+server.js export async function GET() { return new Response( ` <?xml version="1.0" encoding="UTF-8" ?> <urlset xmlns="https://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="https://www.w3.org/1999/xhtml" xmlns:mobile="https://www.google.com/schemas/sitemap-mobile/1.0" xmlns:news="https://www.google.com/schemas/sitemap-news/0.9" xmlns:image="https://www.google.com/schemas/sitemap-image/1.1" xmlns:video="https://www.google.com/schemas/sitemap-video/1.1" > <!-- <url>元素放在这里 --> </urlset>`.trim(), { headers: { 'Content-Type': 'application/xml' } } ); } ``` ### AMP 现代网络开发的一个不幸现实是有时需要创建网站的[加速移动页面（AMP）](https://amp.dev/)版本。在 SvelteKit 中，这可以通过设置 [`inlineStyleThreshold`](configuration#inlineStyleThreshold) 选项来实现... ```js /// file: svelte.config.js /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { // 由于不允许使用<link rel="stylesheet">， // 内联所有样式 inlineStyleThreshold: Infinity } }; export default config; ``` ...在根 `+layout.js`/`+layout.server.js` 中禁用 `csr`... ```js /// file: src/routes/+layout.server.js export const csr = false; ``` ...在`app.html`中添加`amp`... ```html <html amp> ... </html> ``` ...并使用从 `@sveltejs/amp` 导入的 `transform` 和 `transformPageChunk` 转换 HTML： ```js /// file: src/hooks.server.js import * as amp from '@sveltejs/amp'; /** @type {import('@sveltejs/kit').Handle} */ export async function handle({ event, resolve }) { let buffer = ''; return await resolve(event, { transformPageChunk: ({ html, done }) => { buffer += html; if (done) return amp.transform(buffer); } }); } ``` 为了防止在将页面转换为 amp 时发送任何未使用的 CSS，我们可以使用[`dropcss`](https://www.npmjs.com/package/dropcss)： ```js // @filename: ambient.d.ts declare module 'dropcss'; // @filename: index.js // ---cut--- /// file: src/hooks.server.js // @errors: 2307 import * as amp from '@sveltejs/amp'; import dropcss from 'dropcss'; /** @type {import('@sveltejs/kit').Handle} */ export async function handle({ event, resolve }) { let buffer = ''; return await resolve(event, { transformPageChunk: ({ html, done }) => { buffer += html; if (done) { let css = ''; const markup = amp .transform(buffer) .replace('⚡', 'amp') // dropcss无法处理此字符 .replace(/<style amp-custom([^>]*?)>([^]+?)<\/style>/, (match, attributes, contents) => { css = contents; return `<style amp-custom${attributes}></style>`; }); css = dropcss({ css, html: markup }).css; return markup.replace('</style>', `${css}</style>`); } } }); } ``` > [!NOTE] 使用 `handle` hook 通过 `amphtml-validator` 验证转换后的 HTML 是个好主意，但由于速度很慢，仅建议在预渲染页面时使用。 # 常见问题 ## 其他资源 请同时查看 [Svelte FAQ](../svelte/faq) 和 [`vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md)，了解这些库相关问题的答案。 ## 我可以用 SvelteKit 制作什么？ SvelteKit 可以用于创建大多数类型的应用程序。开箱即用，SvelteKit 支持许多功能，包括： - 使用 [load](load) 函数和 [API 路由](routing#server) 实现动态页面内容。 - 使用[服务端渲染（SSR）](glossary#SSR)实现 SEO 友好的动态内容。 - 使用 SSR 和 [Form Actions](form-actions) 实现用户友好的渐进式增强交互页面。 - 使用[预渲染](page-options#prerender)实现静态页面。 SvelteKit 还可以通过[适配器](adapters)部署到各种托管架构。在使用 SSR （或在不预渲染的情况下添加服务端逻辑）的情况下，这些功能将被适配到目标后端。一些例子包括： - 使用 [Node.js 后端](adapter-node)的自托管动态 Web 应用。 - 带有后端加载器和 API 部署为远程函数的 serverless web 应用。查看[零配置部署](adapter-auto)了解常用部署选项。 - [静态预渲染站点](adapter-static)，如托管在 CDN 或静态主机上的博客或多页面站点。静态生成的站点不带后端。 - [单页应用（SPA）](single-page-apps)，具有客户端路由和渲染 API 驱动的动态内容。SPA 不带后端且不进行服务端渲染。当将 SvelteKit 与用 PHP、.Net、Java、C、Golang、Rust 等编写的应用打包在一起时，通常会选择这个选项。 - 以上几种方式的混合；一些路由可以是静态的，一些路由可以使用后端函数获取动态信息。这可以通过[页面选项](page-options)配置，其中包括选择退出 SSR 的选项。 为了支持 SSR，需要一个 JS 后端 — 如 Node.js 或基于 Deno 的服务端、serverless function 或 edge function。 还可以编写自定义适配器或利用社区适配器将 SvelteKit 部署到更多平台，如专用服务端环境、浏览器扩展或原生应用。查看[集成](./integrations)了解更多示例和集成。 ## 如何在应用程序中包含 package.json 的详细信息？ 由于 SvelteKit 期望 [`svelte.config.js`](./configuration) 是一个 ES 模块，因此不能直接引用 JSON 文件。如果你想在应用程序中包含应用程序版本号或其他来自 `package.json` 的信息，可以像这样加载 JSON： ```js /// file: svelte.config.js // @filename: index.js /// <reference types="@types/node" /> import { URL } from 'node:url'; // ---cut--- import { readFileSync } from 'node:fs'; import { fileURLToPath } from 'node:url'; const path = fileURLToPath(new URL('package.json', import.meta.url)); const pkg = JSON.parse(readFileSync(path, 'utf8')); ``` ## 如何修复尝试引入包时遇到的错误？ 大多数与引入库相关的问题都是由于打包不正确造成的。你可以通过在 [publint 网站](https://publint.dev/)输入库来检查库的打包是否与 Node.js 兼容。 在检查库是否正确打包时，需要注意以下几点： - `exports` 优先于其他入口点字段，如 `main` 和 `module`。添加 `exports` 字段可能不向后兼容，因为它会阻止深度导入。 - ESM 文件应以 `.mjs` 结尾，除非设置了 `"type": "module"`，在这种情况下，CommonJS 文件应以 `.cjs` 结尾。 - 如果没有定义 `exports`，则应该定义 `main`。它应该是 CommonJS 或 ESM 文件，并遵循上一条规则。如果定义了 `module` 字段，它应该指向 ESM 文件。 - Svelte 组件应该以未编译的 `.svelte` 文件分发，包中的任何 JS 都应以 ESM 形式编写。自定义脚本和样式语言，如 TypeScript 和 SCSS，应该分别预处理为普通的 JS 和 CSS。我们建议使用 [`svelte-package`](./packaging) 来打包 Svelte 库，它会为你完成这些工作。 当库提供 ESM 版本时，它们在浏览器中与 Vite 配合使用效果最好，特别是当它们是 Svelte 组件库的依赖项时。你可以建议库作者提供 ESM 版本。然而，CommonJS（CJS）依赖项也应该可以工作，因为默认情况下，[`vite-plugin-svelte` 会要求 Vite 使用 `esbuild` 预打包它们](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies)并转换为 ESM。 如果你仍然遇到问题，我们建议搜索 [Vite issue 追踪器](https://github.com/vitejs/vite/issues)和相关库的问题 issue。有时可以通过调整 [`optimizeDeps`](https://vitejs.dev/config/#dep-optimization-options) 或 [`ssr`](https://vitejs.dev/config/#ssr-options) 配置值来解决问题，但我们建议这只作为临时解决方案，最终还是应该修复相关库。 ## 如何在 SvelteKit 中使用视图过渡 API？ 虽然 SvelteKit 没有与[视图过渡](https://developer.chrome.com/docs/web-platform/view-transitions/)的特定集成，但你可以在 [`onNavigate`]($app-navigation#onNavigate) 中调用 `document.startViewTransition` 来在每次客户端导航时触发视图过渡。 ```js // @errors: 2339 2810 import { onNavigate } from '$app/navigation'; onNavigate((navigation) => { if (!document.startViewTransition) return; return new Promise((resolve) => { document.startViewTransition(async () => { resolve(); await navigation.complete; }); }); }); ``` 更多信息，请参见 Svelte 博客上的["解锁视图过渡"](/blog/view-transitions)。 ## 如何在 SvelteKit 中使用 X？ 请确保你已阅读了[集成相关的文档部分](./integrations)。如果你仍然遇到问题，以下列出了常见问题的解决方案。 ### 如何设置数据库？ 将查询数据库的代码放在[服务端路由](./routing#server)中 - 不要在 .svelte 文件中查询数据库。你可以创建一个 `db.js` 或类似的文件，该文件立即建立连接并使客户端在整个应用程序中作为单例可访问。你可以在 `hooks.server.js` 中执行任何一次性设置代码，并在需要的任何端点中导入数据库辅助函数。 ### 如何使用依赖于 `document` 或 `window` 的仅客户端库？ 如果你需要访问 `document` 或 `window` 变量，或者需要代码仅在客户端运行，你可以将其包装在 `browser` 检查中： ```js /// <reference types="@sveltejs/kit" /> // ---cut--- import { browser } from '$app/environment'; if (browser) { // 仅客户端代码在这里 } ``` 如果你想在组件首次渲染到 DOM 后运行代码，也可以在 `onMount` 中运行： ```js // @filename: ambient.d.ts // @lib: ES2015 declare module 'some-browser-only-library'; // @filename: index.js // ---cut--- import { onMount } from 'svelte'; onMount(async () => { const { method } = await import('some-browser-only-library'); method('hello world'); }); ``` 如果你想使用的库是无副作用的，你也可以静态导入它，它将在服务端构建中被 tree shake 掉，其中 `onMount` 将自动被替换为一个空操作： ```js // @filename: ambient.d.ts // @lib: ES2015 declare module 'some-browser-only-library'; // @filename: index.js // ---cut--- import { onMount } from 'svelte'; import { method } from 'some-browser-only-library'; onMount(() => { method('hello world'); }); ``` 最后，你也可以考虑使用 `{#await}` 块： ```svelte <!--- file: index.svelte ---> <script> import { browser } from '$app/environment'; const ComponentConstructor = browser ? import('some-browser-only-library').then((module) => module.Component) : new Promise(() => {}); </script> {#await ComponentConstructor} <p>加载中...</p> {:then component} <svelte:component this={component} /> {:catch error} <p>出错了: {error.message}</p> {/await} ``` ### 如何使用不同的后端 API 服务端？ 你可以使用 [`event.fetch`](./load#Making-fetch-requests) 从外部 API 服务端请求数据，但要注意，你需要处理 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)，这将导致一些复杂情况，比如通常需要预检请求，从而导致更高的延迟。对不同子域的请求也可能由于额外的 DNS 查找、TLS 设置等而增加延迟。如果你想使用这种方法，你可能会发现 [`handleFetch`](./hooks#Server-hooks-handleFetch) 很有帮助。 另一种方法是设置代理以绕过 CORS 问题。在生产环境中，你需要将像 `/api` 这样的路径重写到 API 服务端；对于本地开发，使用 Vite 的 [`server.proxy`](https://vitejs.dev/config/server-options.html#server-proxy) 选项。 在生产环境中如何设置重写将取决于你的部署平台。如果重写不是一个选项，你也可以添加一个 [API 路由](./routing#server)： ```js /// file: src/routes/api/[...path]/+server.js /** @type {import('./$types').RequestHandler} */ export function GET({ params, url }) { return fetch(`https://my-api-server.com/${params.path + url.search}`); } ``` （注意，根据你的需求，你可能还需要代理 `POST`/`PATCH` 等请求，并转发 `request.headers`。） ### 如何使用中间件？ `adapter-node` 构建了一个中间件，你可以在生产模式下与你自己的服务端一起使用。在开发中，你可以使用 Vite 插件向 Vite 添加中间件。例如： ```js // @errors: 2322 // @filename: ambient.d.ts declare module '@sveltejs/kit/vite'; // @filename: index.js // ---cut--- import { sveltekit } from '@sveltejs/kit/vite'; /** @type {import('vite').Plugin} */ const myPlugin = { name: 'log-request-middleware', configureServer(server) { server.middlewares.use((req, res, next) => { console.log(`收到请求 ${req.url}`); next(); }); } }; /** @type {import('vite').UserConfig} */ const config = { plugins: [myPlugin, sveltekit()] }; export default config; ``` 有关更多详细信息，包括如何控制顺序，请参见 [Vite 的 `configureServer` 文档](https://vitejs.dev/guide/api-plugin.html#configureserver)。 ### 它能与 Yarn 2 一起工作吗？ 某种程度上可以。Plug'n'Play 功能（简称 'pnp'）是有问题的（它偏离了 Node 模块解析算法，并且[尚不支持原生 JavaScript 模块](https://github.com/yarnpkg/berry/issues/638)，而 SvelteKit 以及[越来越多的包](https://blog.sindresorhus.com/get-ready-for-esm-aa53530b3f77)都在使用这个特性）。你可以在 [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) 文件中使用 `nodeLinker: 'node-modules'` 来禁用 pnp，但使用 npm 或 [pnpm](https://pnpm.io/) 可能更容易，它们同样快速和高效，但没有兼容性问题。 ### 如何使用 Yarn 3？ 目前在最新的 Yarn（版本 3）中的 ESM 支持被认为是[实验性的](https://github.com/yarnpkg/berry/pull/2161)。 下面的方法似乎可行，但你的结果可能会有所不同。 首先创建一个新应用： ```sh yarn create svelte myapp cd myapp ``` 启用 Yarn Berry： ```sh yarn set version berry yarn install ``` #### Yarn 3 全局缓存 Yarn Berry 的一个更有趣的特性是能够拥有一个全局包缓存，而不是在磁盘上为每个项目都有多个副本。但是，将 `enableGlobalCache` 设置为 true 会导致构建失败，所以建议在 `.yarnrc.yml` 文件中添加以下内容： ```yaml nodeLinker: node-modules ``` 这将导致包被下载到本地的 node_modules 目录中，但避免了上述问题，这是目前使用 Yarn 版本 3 的最佳选择。 # 集成 ## `vitePreprocess` 在您的项目中包含 [`vitePreprocess`](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/preprocess.md) 将允许您使用 Vite 支持的各种 CSS 风格：PostCSS、SCSS、Less、Stylus 和 SugarSS。如果您使用 TypeScript 设置项目，它会默认包含： ```js // svelte.config.js import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'; export default { preprocess: [vitePreprocess()] }; ``` 如果您在 Svelte 4 中使用 TypeScript，您还需要使用预处理器。在 Svelte 5 中，如果您只使用类型语法，TypeScript 是原生支持的。要在 Svelte 5 中使用更复杂的 TypeScript 语法，您仍然需要预处理器，可以使用 `vitePreprocess({ script: true })`。 ## 添加器 运行 `npx sv add` 可以通过单个命令设置多个复杂的集成，包括： - prettier（格式化） - eslint（代码检查） - vitest（单元测试） - playwright（端到端测试） - lucia（认证） - tailwind（CSS） - drizzle（数据库） - paraglide（国际化） - mdsvex（markdown） - storybook（前端工作坊） ## 目录 访问 [sveltesociety.dev](https://sveltesociety.dev/) 查看完整的可用于 Svelte 和 SvelteKit 的[包](https://sveltesociety.dev/packages)和[模板](https://sveltesociety.dev/templates)列表。 ## 其他集成 ### `svelte-preprocess` `svelte-preprocess` 有一些 `vitePreprocess` 中没有的额外功能，比如支持 Pug、Babel 和全局样式。但是，`vitePreprocess` 可能更快且需要更少的配置，所以它是默认使用的。注意，SvelteKit 不[支持](https://github.com/sveltejs/kit/issues/2920#issuecomment-996469815) CoffeeScript。 您需要通过 `npm install --save-dev svelte-preprocess` 安装 `svelte-preprocess` 并[将其添加到您的 `svelte.config.js` 中](https://github.com/sveltejs/svelte-preprocess/blob/main/docs/usage.md#with-svelte-config)。之后，您通常需要[安装相应的库](https://github.com/sveltejs/svelte-preprocess/blob/main/docs/getting-started.md)，比如 `npm install -D sass` 或 `npm install -D less`。 ## Vite 插件 由于 SvelteKit 项目是用 Vite 构建的，您可以使用 Vite 插件来增强您的项目。在 [`vitejs/awesome-vite`](https://github.com/vitejs/awesome-vite?tab=readme-ov-file#plugins) 查看可用插件列表。 ## 集成常见问题 SvelteKit FAQ 有一个[如何在 SvelteKit 中使用 X](./faq#How-do-I-use-X-with-SvelteKit) 的部分，如果您还有问题，这可能会有帮助。 # 断点调试 除了 [`@debug`](../svelte/@debug) 标签外，您还可以使用各种工具和开发环境中的断点来调试 Svelte 和 SvelteKit 项目。这包括前端和后端代码。 以下指南假设您的 JavaScript 运行时环境是 Node.js。 ## Visual Studio Code 通过内置的调试终端，您可以在 VSCode 中的源文件中设置断点。 1. 打开命令面板：`CMD/Ctrl` + `Shift` + `P`。 2. 找到并启动"调试：JavaScript 调试终端"。 3. 使用调试终端启动您的项目。例如：`npm run dev`。 4. 在您的客户端或服务端源代码中设置一些断点。 5. 触发断点。 ### 通过调试面板启动 您也可以在项目中设置一个 `.vscode/launch.json`。要自动设置： 1. 转到"运行和调试"面板。 2. 在"运行"选择菜单中，选择"Node.js..."。 3. 选择与您的项目对应的"运行脚本"，例如"运行脚本：dev"。 4. 按下"开始调试"播放按钮，或按 `F5` 开始断点调试。 这是一个 `launch.json` 示例： ```json { "version": "0.2.0", "configurations": [ { "command": "npm run dev", "name": "运行开发服务端", "request": "launch", "type": "node-terminal" } ] } ``` 更多阅读：<https://code.visualstudio.com/docs/editor/debugging>。 ## 其他编辑器 如果您使用其他编辑器，这些社区指南可能对您有用： - [WebStorm Svelte：调试您的应用程序](https://www.jetbrains.com/help/webstorm/svelte.html#ws_svelte_debug) - [在 Neovim 中调试 JavaScript 框架](https://theosteiner.de/debugging-javascript-frameworks-in-neovim) ## Google Chrome 和 Microsoft Edge 开发者工具 可以使用基于浏览器的调试器来调试 Node.js 应用程序。 > [!NOTE] 注意这只适用于调试客户端 SvelteKit 源映射。 1. 使用 Node.js 启动 Vite 服务端时运行 `--inspect` 标志。例如：`NODE_OPTIONS="--inspect" npm run dev` 2. 在新标签页中打开您的网站。通常在 `localhost:5173`。 3. 打开浏览器的开发者工具，点击左上角附近的"为 Node.js 打开专用 DevTools"图标。它应该显示 Node.js 标志。 4. 设置断点并调试您的应用程序。 您也可以通过在 Google Chrome 中导航到 `chrome://inspect`，或在 Microsoft Edge 中导航到 `edge://inspect` 来打开调试器开发工具。 ## 参考资料 - [调试 Node.js](https://nodejs.org/en/learn/getting-started/debugging) # 迁移到 SvelteKit v2 从 SvelteKit 版本 1 升级到版本 2 应该基本上是无缝的。这里列出了一些需要注意的重大变更。您可以使用 `npx sv migrate sveltekit-2` 来自动迁移其中的一些变更。 我们强烈建议在升级到 2.0 之前先升级到最新的 1.x 版本，这样您就可以利用有针对性的弃用警告。我们还建议先[升级到 Svelte 4](../svelte/v4-migration-guide)：SvelteKit 1.x 的后期版本支持它，而 SvelteKit 2.0 则需要它。 ## `redirect` 和 `error` 不再需要您来抛出 之前，您必须自己 `throw` 从 `error(...)` 和 `redirect(...)` 返回的值。在 SvelteKit 2 中不再需要这样做 — 调用这些函数就足够了。 ```js import { error } from '@sveltejs/kit' // ... ---throw error(500, '出错了');--- +++error(500, '出错了');+++ ``` `svelte-migrate` 将为您自动完成这些更改。 如果错误或重定向是在 `try {...}` 块内抛出的（提示：不要这样做！），您可以使用从 `@sveltejs/kit` 导入的 [`isHttpError`](@sveltejs-kit#isHttpError) 和 [`isRedirect`](@sveltejs-kit#isRedirect) 来区分它们和意外错误。 ## 设置 cookie 时需要 path 当接收到没有指定 `path` 的 `Set-Cookie` 头时，浏览器会[设置 cookie 路径](https://www.rfc-editor.org/rfc/rfc6265#section-5.1.4)为相关资源的父路径。这种行为既不实用也不直观，而且经常导致bug，因为开发者期望 cookie 适用于整个域名。 从 SvelteKit 2.0 开始，在调用 `cookies.set(...)`、`cookies.delete(...)` 或 `cookies.serialize(...)` 时需要设置 `path`，以避免歧义。大多数情况下，您可能想使用 `path: '/'`，但您也可以设置其他路径，包括相对路径 — `''` 表示"当前路径"，`'.'` 表示"当前目录"。 ```js /** @type {import('./$types').PageServerLoad} */ export function load({ cookies }) { cookies.set(name, value, +++{ path: '/' }+++); return { response } } ``` `svelte-migrate` 将添加注释来突出显示需要调整的位置。 ## 顶级 promise 不再自动等待 在 SvelteKit 版本 1 中，如果从 `load` 函数返回的对象的顶级属性是 promise，它们会被自动等待。随着[流式传输](/blog/streaming-snapshots-sveltekit)的引入，这种行为变得有点尴尬，因为它强制您将流式数据嵌套在一层深度。 从版本 2 开始，SvelteKit 不再区分顶级和非顶级 promise。要恢复阻塞行为，请使用 `await`（在适当的情况下使用 `Promise.all` 来防止瀑布效应）： ```js // @filename: ambient.d.ts declare const url: string; // @filename: index.js // ---cut--- // If you have a single promise /** @type {import('./$types').PageServerLoad} */ export +++async+++ function load({ fetch }) { const response = +++await+++ fetch(url).then(r => r.json()); return { response } } ``` ```js // @filename: ambient.d.ts declare const url1: string; declare const url2: string; // @filename: index.js // ---cut--- // If you have multiple promises /** @type {import('./$types').PageServerLoad} */ export +++async+++ function load({ fetch }) { --- const a = fetch(url1).then(r => r.json());--- --- const b = fetch(url2).then(r => r.json());--- +++ const [a, b] = await Promise.all([ fetch(url1).then(r => r.json()), fetch(url2).then(r => r.json()), ]);+++ return { a, b }; } ``` ## goto(...) 修改 `goto(...)` 不再接受外部 URL。若需跳转到外部 URL，请使用 `window.location.href = url`。现在 `state` 对象决定了 `$page.state`，并且必须遵循已声明的 `App.PageState` 接口。详情参考 [浅层路由](shallow-routing)。 ## 路径默认改为相对路径 在 SvelteKit 1 中，`app.html` 中的 `%sveltekit.assets%` 在服务端渲染时默认会被替换为相对路径（例如 `.` 或 `..` 或 `../..` 等，取决于渲染路径），除非显式将 [`paths.relative`](configuration#paths) 配置选项设置为 `false`。对于从 `$app/paths` 导入的 `base` 和 `assets`，也是类似的情况，但前提是 `paths.relative` 配置选项显式设置为 `true`。 在版本 2 中，这种不一致性已经修复。路径要么始终是相对路径，要么始终是绝对路径，具体取决于 [`paths.relative`](configuration#paths) 的值。默认值为 `true`，因为这让应用程序更加便携：如果 `base` 超出了应用程序的预期（例如当您在 [Internet Archive](https://archive.org/) 查看时）或者在构建时未知（例如部署到 [IPFS](https://ipfs.tech/) 等情况），破坏的可能性会更低。 ## 服务端 fetch 请求不再可追踪 之前可以通过在服务端上的 `fetch` 请求追踪请求的 URL 以重新运行加载函数。但这可能会造成安全风险（私有 URL 泄露），因此该功能在之前由 `dangerZone.trackServerFetches` 设置控制，现在该设置已被移除。 ## `preloadCode` 参数必须以 `base` 为前缀 SvelteKit 提供了两个函数，[`preloadCode`]($app-navigation#preloadCode) 和 [`preloadData`]($app-navigation#preloadData)，用于以编程方式加载与特定路径相关的代码和数据。在版本 1 中存在一个细微的不一致性——传递给 `preloadCode` 的路径不需要加上 `base` 路径（如果设置了），而传递给 `preloadData` 的路径则要求这样做。 这一问题在 SvelteKit 2 中已修复——在两种情况下，路径都应该以 `base` 为前缀（如果设置了该值）。 此外，`preloadCode` 现在只接受一个参数，而不是多个参数。 ## `resolvePath` 已被移除 SvelteKit 1 包含一个名为 `resolvePath` 的函数，用于将路由 ID（如 `/blog/[slug]`）和一组参数（如 `{ slug: 'hello' }`）解析为路径名。然而，其返回值并不包括 `base` 路径，这在 `base` 被设置的情况下限制了其实用性。 因此，SvelteKit 2 用一个更合适命名的函数 `resolveRoute` 替代了 `resolvePath`，该函数从 `$app/paths` 导入，并且会考虑到 `base` 路径。 ```js ---import { resolvePath } from '@sveltejs/kit'; import { base } from '$app/paths';--- +++import { resolveRoute } from '$app/paths';+++ ---const path = base + resolvePath('/blog/[slug]', { slug });--- +++const path = resolveRoute('/blog/[slug]', { slug });+++ ``` `svelte-migrate` 会替您完成方法替换，但如果您随后在结果前加了 `base`，需要自行移除。 ## 改进的错误处理 在 SvelteKit 1 中，错误处理不一致。一些错误会触发 `handleError` 钩子，但无法很好地区分状态（例如，判别 404 和 500 的唯一方法是查看 `event.route.id` 是否为 `null`）；而另一些错误（比如没有 actions 的页面对 `POST` 请求的 405 错误）却完全不会触发 `handleError`，尽管它们应该触发。在后者的情况下，生成的 `$page.error` 会偏离 [`App.Error`](types#Error) 类型（如果已指定）。 SvelteKit 2 通过为 `handleError` 钩子添加两个新属性 `status` 和 `message` 来清理了这一问题。对于从您的代码（或调用您的代码的库代码）抛出的错误，状态将为 `500`，消息将为 `Internal Error`。虽然 `error.message` 可能包含不应向用户暴露的敏感信息，但 `message` 是安全的。 ## 动态环境变量不能在预渲染期间使用 `$env/dynamic/public` 和 `$env/dynamic/private` 模块提供了访问运行时环境变量的功能，而与 `$env/static/public` 和 `$env/static/private` 暴露的构建时环境变量不同。 在 SvelteKit 1 中，它们是相同的。因此，使用了“动态”环境变量的预渲染页面实际上“内嵌”了构建时的值，这是错误的。更糟的是，如果用户在导航到动态渲染页面之前恰好访问了预渲染页面，`$env/dynamic/public` 在浏览器中会填充这些过时的值。 因此，SvelteKit 2 中动态环境变量在预渲染期间不再可读——您应该使用 `static` 模块。如果用户访问了预渲染页面，SvelteKit 将向服务端请求 `$env/dynamic/public` 的最新值（默认从名为 `_env.js` 的模块中获取——可以通过 `config.kit.env.publicModule` 配置），而不是从服务端渲染的 HTML 中读取它们。 ## `use:enhance` 回调中的 `form` 和 `data` 已被移除 如果您为 [`use:enhance`](form-actions#Progressive-enhancement-use:enhance) 提供一个回调，它会被调用时带有包含各种有用属性的对象。 在 SvelteKit 1 中，这些属性包括 `form` 和 `data`。这些属性很早之前就被弃用，改用了 `formElement` 和 `formData`，现在它们在 SvelteKit 2 中已完全移除。 ## 包含文件输入的表单必须使用 `multipart/form-data` 如果一个表单包含 `<input type="file">`，但未设置 `enctype="multipart/form-data"` 属性，非 JS 提交将会忽略文件。在进行 `use:enhance` 提交时，如果遇到这样的表单，SvelteKit 2 会抛出错误，从而确保在无 JavaScript 的情况下您的表单能正常工作。 ## 生成的 `tsconfig.json` 更加严格 之前，生成的 `tsconfig.json` 会尽力在您的 `tsconfig.json` 中包含 `paths` 或 `baseUrl` 时生成一个看上去有效的配置。在 SvelteKit 2 中，验证更加严格，如果您在 `tsconfig.json` 中使用了 `paths` 或 `baseUrl`，会发出警告。这些设置被用来生成路径别名，您应该在 `svelte.config.js` 中使用 [别名配置](configuration#alias) 来创建对应的别名，以同时为打包器创建别名。 ## `getRequest` 不再抛出错误 `@sveltejs/kit/node` 模块在 Node 环境中提供了一些辅助函数，其中包括 `getRequest`，它可以将 Node 的 [`ClientRequest`](https://nodejs.org/api/http.html#class-httpclientrequest) 转换为标准 [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) 对象。 在 SvelteKit 1 中，如果 `Content-Length` 头超过指定的大小限制，`getRequest` 可能会抛出错误。在 SvelteKit 2 中，这种错误在请求体（如果存在）被读取时才会抛出。这样可以实现更好的诊断和更简单的代码。 ## `vitePreprocess` 不再从 `@sveltejs/kit/vite` 导出 由于 `@sveltejs/vite-plugin-svelte` 现在是一个 peer 依赖，SvelteKit 2 不再重新导出 `vitePreprocess`。您应该直接从 `@sveltejs/vite-plugin-svelte` 导入它。 ## 更新依赖要求 SvelteKit 2 要求 Node `18.13` 或更高版本，以及以下最低依赖版本： - `svelte@4` - `vite@5` - `typescript@5` - `@sveltejs/vite-plugin-svelte@3`（现在作为 SvelteKit 的 `peerDependency`，之前是直接依赖） - `@sveltejs/adapter-cloudflare@3`（如果您在使用这些适配器） - `@sveltejs/adapter-cloudflare-workers@2` - `@sveltejs/adapter-netlify@3` - `@sveltejs/adapter-node@2` - `@sveltejs/adapter-static@3` - `@sveltejs/adapter-vercel@4` `svelte-migrate` 会帮您更新 `package.json`。 作为 TypeScript 升级的一部分，生成的 `tsconfig.json`（您的 `tsconfig.json` 会扩展它）现在使用 `"moduleResolution": "bundler"`（这是 TypeScript 团队推荐的方案，因为它能正确解析包中带有 `exports` 映射的类型）和 `verbatimModuleSyntax`（用以替代现有的 `importsNotUsedAsValues` 和 `preserveValueImports` 标志——如果您的 `tsconfig.json` 中有这些字段，请移除它们，`svelte-migrate` 会为您完成这些操作）。 ## SvelteKit 2.12: `$app/stores` 被弃用 SvelteKit 2.12 引入了基于 [Svelte 5 Runes API](/docs/svelte/what-are-runes) 的 `$app/state`。`$app/state` 提供了 `$app/stores` 的所有功能，但在使用位置和方式上更加灵活。最重要的是，`page` 对象现在是细粒度的，例如 `page.state` 的更新不会使 `page.data` 无效，反之亦然。 因此，`$app/stores` 已被弃用，并将在 SvelteKit 3 中移除。我们建议您 [升级到 Svelte 5](/docs/svelte/v5-migration-guide)，如果尚未完成，并迁移所有 `$app/stores` 的用法。大多数替换应该相当简单：将 `$app/stores` 导入替换为 `$app/state`，并移除各个使用点的 `$` 前缀。 ```svelte <script> ---import { page } from '$app/stores';--- +++import { page } from '$app/state';+++ </script> ---{$page.data}--- +++{page.data}+++ ``` 使用 `npx sv migrate app-state` 自动迁移 .svelte 组件中绝大多数 `$app/stores` 的用法。 # 从 Sapper 迁移 SvelteKit 是 Sapper 的继任者，它们共享许多设计元素。 如果您有一个现有的 Sapper 应用想要迁移到 SvelteKit，您需要进行一些更改。在迁移过程中，查看[一些示例](additional-resources#Examples)可能会有所帮助。 ## package.json ### type: "module" 在您的 `package.json` 中添加 `"type": "module"`。如果您使用的是 Sapper 0.29.3 或更新版本，您可以将此步骤作为渐进式迁移的一部分单独进行。 ### dependencies 如果您使用了 `polka` 或 `express`，请移除它们，以及任何中间件，如 `sirv` 或 `compression`。 ### devDependencies 从您的 `devDependencies` 中移除 `sapper`，并替换为 `@sveltejs/kit` 和您计划使用的[适配器](adapters)（参见[下一节](migrating#Project-files-Configuration)）。 ### scripts 任何引用 `sapper` 的脚本都应该更新： - `sapper build` 应改为使用 Node [适配器](adapters)的 `vite build` - `sapper export` 应改为使用静态[适配器](adapters)的 `vite build` - `sapper dev` 应改为 `vite dev` - `node __sapper__/build` 应改为 `node build` ## 项目文件 您的应用程序的主体部分，即 `src/routes` 中的内容可以保持原样，但需要移动或更新几个项目文件。 ### 配置 您的 `webpack.config.js` 或 `rollup.config.js` 应该替换为 `svelte.config.js`，如[此处](configuration)所述。Svelte 预处理器选项应移至 `config.preprocess`。 您需要添加一个[适配器](adapters)。`sapper build` 大致相当于 [adapter-node](https://github.com/sveltejs/kit/tree/main/packages/adapter-node)，而 `sapper export` 大致相当于 [adapter-static](https://github.com/sveltejs/kit/tree/main/packages/adapter-static)，不过您可能更倾向于使用专门为您部署的平台设计的适配器。 如果您之前使用的插件用于处理 [Vite](https://vitejs.dev) 不会自动处理的文件类型，您需要找到 Vite 的等效插件并将它们添加到 [Vite 配置](project-structure#Project-files-vite.config.js)中。 ### src/client.js 此文件在 SvelteKit 中没有对应的文件。任何自定义逻辑（除了 `sapper.start(...)`）都应该在您的 `+layout.svelte` 文件中的 `onMount` 回调内表达。 ### src/server.js 当使用 `adapter-node` 时，对应的是[自定义服务端](adapter-node#Custom-server)。否则，此文件没有直接对应的文件，因为 SvelteKit 应用可以在无服务端环境中运行。 ### src/service-worker.js 大多数从 `@sapper/service-worker` 导入的内容在 [`$service-worker`]($service-worker) 中都有对应项： - `files` 保持不变 - `routes` 已被移除 - `shell` 现在是 `build` - `timestamp` 现在是 `version` ### src/template.html `src/template.html` 文件应重命名为 `src/app.html`。 移除 `%sapper.base%`、`%sapper.scripts%` 和 `%sapper.styles%`。将 `%sapper.head%` 替换为 `%sveltekit.head%`，将 `%sapper.html%` 替换为 `%sveltekit.body%`。`<div id="sapper">` 不再需要。 ### src/node_modules Sapper 应用中的一个常见模式是将内部库放在 `src/node_modules` 目录中。这在 Vite 中不起作用，所以我们改用 [`src/lib`]($lib)。 ## 页面和布局 ### 重命名文件 现在路由仅由文件夹名称构成以消除歧义，通向 `+page.svelte` 的文件夹名称对应于路由。查看[路由文档](routing)了解概述。以下是旧文件和新文件的对比： | 旧 | 新 | | ------------------------- | ------------------------- | | routes/about/index.svelte | routes/about/+page.svelte | | routes/about.svelte | routes/about/+page.svelte | 您的自定义错误页面组件应从 `_error.svelte` 重命名为 `+error.svelte`。任何 `_layout.svelte` 文件同样应重命名为 `+layout.svelte`。[其他文件将被忽略](routing#Other-files)。 ### 引入 从 `@sapper/app` 导入的 `goto`、`prefetch` 和 `prefetchRoutes` 应分别替换为从 [`$app/navigation`]($app-navigation) 导入的 `goto`、`preloadData` 和 `preloadCode`。 从 `@sapper/app` 的 `stores` 导入应被替换 — 请参阅下面的[Stores (存储)](migrating#Pages-and-layouts-Stores)部分。 之前从 `src/node_modules` 目录中导入的任何文件现在需要用 [`$lib`]($lib) 导入替换。 ### Preload 如之前一样，页面和布局可以导出一个函数，该函数允许在渲染发生之前加载数据。 此函数名称从 `preload` 重命名为 [`load`](load)，现在它位于紧邻其 `+page.svelte`（或 `+layout.svelte`）的 `+page.js`（或 `+layout.js`）中，且其 API 已更改。不再是两个参数 — `page` 和 `session` — 而是一个单一的 `event` 参数。 不再有 `this` 对象，因此也没有 `this.fetch`、`this.error` 或 `this.redirect`。取而代之的是，您可以从输入方法中获取 [`fetch`](load#Making-fetch-requests)，[`error`](load#Errors) 和 [`redirect`](load#Redirects) 现在通过抛出实现。 ### 存储 (Stores) 在 Sapper 中，您可以这样获取提供的存储的引用： ```js // @filename: ambient.d.ts declare module '@sapper/app'; // @filename: index.js // ---cut--- import { stores } from '@sapper/app'; const { preloading, page, session } = stores(); ``` `page` 存储仍然存在；`preloading` 被替换为具有 `from` 和 `to` 属性的 `navigating` 存储。`page` 现在有 `url` 和 `params` 属性，但没有 `path` 或 `query`。 在 SvelteKit 中访问它们的方式有所不同。`stores` 现在是 `getStores`，但在大多数情况下，这是不必要的，因为您可以直接从 [`$app/stores`]($app-stores) 导入 `navigating` 和 `page`。如果您使用的是 Svelte 5 和 SvelteKit 2.12 或更高版本，请考虑使用 [`$app/state`]($app-state)。 ### 路由 (Routing) 不再支持正则路由。取而代之的是使用[高级路由匹配](advanced-routing#Matching)。 ### 段 (Segments) 以前，布局组件会接收一个 `segment` 属性，指示子段。这已被移除；您应该使用更灵活的 `$page.url.pathname`（或 `page.url.pathname`）值来派生您感兴趣的段。 ### URL 在 Sapper 中，所有相对 URL 都是相对于基本 URL 解析的 — 通常是 `/`，除非使用了 `basepath` 选项 — 而不是相对于当前页面。 这导致了一些问题，现在在 SvelteKit 中不再这样了。相对 URL 是相对于当前页面解析的（对于 `load` 函数中的 `fetch` URL，解析为目标页面）。在大多数情况下，使用根相对 URL（即以 `/` 开头）更简单，因为它们的意义不依赖于上下文。 ### <a> 属性 - `sapper:prefetch` 现在是 `data-sveltekit-preload-data` - `sapper:noscroll` 现在是 `data-sveltekit-noscroll` ## 端点 (Endpoints) 在 Sapper 中，[服务端路由](routing#server) 接收由 Node 的 `http` 模块暴露的 `req` 和 `res` 对象（或由框架如 Polka 和 Express 提供增强的版本）。 SvelteKit 被设计成可以与应用运行的环境无关 — 它可以运行在 Node 服务端，也可以运行在无服务端平台或 Cloudflare Worker 中。因此，您不能再直接与 `req` 和 `res` 交互。您的端点需要更新以符合新签名。 为了支持这种与环境无关的行为，`fetch` 现在在全局上下文中可用，因此不需要引入 `node-fetch`、`cross-fetch` 或类似的服务端 fetch 实现来使用它。 ## 集成 (Integrations) 参阅[集成文档](./integrations)了解集成的详细信息。 ### HTML 压缩器 Sapper 默认包含 `html-minifier`。SvelteKit 没有包含此功能，但您可以将其添加为生产依赖，然后通过[钩子](hooks#Server-hooks-handle)使用： ```js // @filename: ambient.d.ts /// <reference types="@sveltejs/kit" /> declare module 'html-minifier'; // @filename: index.js // ---cut--- import { minify } from 'html-minifier'; import { building } from '$app/environment'; const minification_options = { collapseBooleanAttributes: true, collapseWhitespace: true, conservativeCollapse: true, decodeEntities: true, html5: true, ignoreCustomComments: [/^#/], minifyCSS: true, minifyJS: false, removeAttributeQuotes: true, removeComments: false, // 一些 hydration 代码需要注释，所以保留它们 removeOptionalTags: true, removeRedundantAttributes: true, removeScriptTypeAttributes: true, removeStyleLinkTypeAttributes: true, sortAttributes: true, sortClassName: true }; /** @type {import('@sveltejs/kit').Handle} */ export async function handle({ event, resolve }) { let page = ''; return resolve(event, { transformPageChunk: ({ html, done }) => { page += html; if (done) { return building ? minify(page, minification_options) : page; } } }); } ``` 请注意，当使用 `vite preview` 测试生产构建的站点时，`prerendering` 为 `false`，因此要验证压缩效果，您需要直接检查生成的 HTML 文件。 # 额外资源 ## 常见问题 请查看 [SvelteKit 常见问题](faq) 以获取常见问题的解决方案以及有用的提示和技巧。 对于源自这些库的问题，[Svelte 常见问题](../svelte/faq) 和 [`vite-plugin-svelte` 常见问题](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md) 也可能会有帮助。 ## 示例 我们编写并发布了几个不同的 SvelteKit 站点作为示例： - [`sveltejs/realworld`](https://github.com/sveltejs/realworld) 包含一个示例博客网站 - [HackerNews 克隆版](https://github.com/sveltejs/sites/tree/master/sites/hn.svelte.dev) - [`svelte.dev`](https://github.com/sveltejs/svelte.dev) SvelteKit 用户也在 GitHub 上发布了大量示例，可以在 [#sveltekit](https://github.com/topics/sveltekit) 和 [#sveltekit-template](https://github.com/topics/sveltekit-template) 主题下找到，以及在 [Svelte Society 网站](https://sveltesociety.dev/templates?category=sveltekit) 上找到。请注意，这些示例未经维护人员审核，可能不是最新的。 ## 支持 您可以在 [Discord](/chat) 和 [StackOverflow](https://stackoverflow.com/questions/tagged/sveltekit) 上寻求帮助。为了尊重他人的时间，请首先在常见问题、Google 或其他搜索引擎、issue tracker 和 Discord 聊天历史记录中搜索与您的问题相关的信息。提问的人远多于回答的人，这将有助于社区以可扩展的方式成长。 # 术语表 SvelteKit 的核心提供了一个高度可配置的渲染引擎。本节描述了在讨论渲染时使用的一些术语。上述文档中提供了设置这些选项的参考。 ## CSR 客户端渲染（CSR）是使用 JavaScript 在 web 浏览器中生成页面内容。 在 SvelteKit 中，默认会使用客户端渲染，但您可以通过[`csr = false` 页面选项](page-options#csr)关闭 JavaScript。 ## 水合（Hydration） Svelte 组件存储一些状态，并在状态更新时更新 DOM。在 SSR 期间获取数据时，SvelteKit 默认会存储这些数据，并将其与服务端渲染的 HTML 一起传输到客户端。然后，组件可以使用该数据在客户端上初始化，而无需再次调用相同的 API 端点。Svelte 随后会检查 DOM 是否处于预期状态，并在一个称为水合的过程中添加事件监听器。一旦组件完全水合，它们就可以像任何新创建的 Svelte 组件一样对其属性的变化做出反应。 在 SvelteKit 中，页面默认会被水合，但您可以通过[`csr = false` 页面选项](page-options#csr)关闭 JavaScript。 ## 预渲染（Prerendering） 预渲染意味着在构建时计算页面内容并保存 HTML 以供显示。这种方法具有与传统服务端渲染页面相同的优势，但避免了为每个访问者重新计算页面，因此随着访问者数量的增加，几乎可以免费扩展。权衡之处在于构建过程更加耗费资源，并且预渲染的内容只能通过构建和部署应用程序的新版本来更新。 并非所有页面都可以预渲染。基本规则是：要使内容可预渲染，任何两个直接访问它的用户必须从服务端获得相同的内容，并且页面不能包含 [actions](form-actions)。请注意，只要所有用户都会看到相同的预渲染内容，您仍然可以预渲染基于页面参数加载的内容。 预渲染的页面并不限于静态内容。如果用户特定的数据是在客户端获取和渲染的，您可以构建个性化页面。这受制于上述不做 SSR 的内容的缺点。 在 SvelteKit 中，您可以通过[`prerender` 页面选项](page-options#prerender)和 `svelte.config.js` 中的 [`prerender` 配置](configuration#prerender)控制预渲染。 ## 路由（Routing） 默认情况下，当您导航到新页面时（通过点击链接或使用浏览器的前进或后退按钮），SvelteKit 将拦截尝试的导航，而不是允许浏览器向服务端发送目标页面的请求。然后，SvelteKit 将通过渲染新页面的组件来更新客户端显示的内容，这反过来可以调用必要的 API 端点。这种根据尝试的导航在客户端更新页面的过程称为客户端路由。 在 SvelteKit 中，默认会使用客户端路由，但您可以通过 [`data-sveltekit-reload`](link-options#data-sveltekit-reload) 跳过它。 ## SPA 单页应用（SPA）是一种应用程序，其中所有对服务端的请求都加载单个 HTML 文件，然后根据请求的 URL 对请求的内容进行客户端渲染。所有导航都在客户端处理，这个过程称为客户端路由，每页内容都会更新，而常见的布局元素基本保持不变。SPA 不提供 SSR，这具有上述缺点。然而，某些应用程序不会受到这些缺点的重大影响，比如登录后的复杂业务应用程序，在这种情况下 SEO 不重要，并且已知用户将从一致的计算环境访问应用程序。 在 SvelteKit 中，您可以[使用 `adapter-static` 构建 SPA](single-page-apps)。 ## SSG 静态站点生成（SSG）是指每个页面都预渲染的站点。SvelteKit 不是为仅做静态站点生成而构建的，因此在高效渲染大量页面方面可能不如专门为此目的构建的工具。然而，与大多数专门构建的 SSG 相比，SvelteKit 确实很好地允许在不同页面上混合和匹配不同的渲染类型。完全预渲染站点的一个好处是您不需要维护或支付服务端来执行 SSR。一旦生成，站点就可以从 CDN 提供服务，从而带来出色的"首字节时间"性能。这种交付模型通常被称为 JAMstack。 在 SvelteKit 中，您可以通过使用 [`adapter-static`](adapter-static) 或通过使用[`prerender` 页面选项](page-options#prerender)或 `svelte.config.js` 中的 [`prerender` 配置](configuration#prerender)配置每个页面预渲染来进行静态站点生成。 ## SSR 服务端渲染（SSR）是在服务端上生成页面内容。SSR 通常是 SEO 的首选。虽然一些搜索引擎可以索引在客户端动态生成的内容，但在这些情况下可能需要更长的时间。它还倾向于提高感知性能，并使您的应用程序在 JavaScript 失败或被禁用时对用户可访问（这种情况[发生的频率可能比您想象的要高](https://kryogenix.org/code/browser/everyonehasjs.html)）。 在 SvelteKit 中，页面默认是服务端渲染的。您可以通过[`ssr` 页面选项](page-options#ssr)禁用 SSR。 # @sveltejs/kit ```js // @noErrors import { Server, VERSION, error, fail, isActionFailure, isHttpError, isRedirect, json, redirect, text } from '@sveltejs/kit'; ``` ## Server <div class="ts-block"> ```dts class Server {/*…*/} ``` <div class="ts-block-property"> ```dts constructor(manifest: SSRManifest); ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts init(options: ServerInitOptions): Promise<void>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts respond(request: Request, options: RequestOptions): Promise<Response>; ``` <div class="ts-block-property-details"></div> </div></div> ## VERSION <div class="ts-block"> ```dts const VERSION: string; ``` </div> ## error 抛出一个带有 HTTP 状态码和可选消息的错误。在请求处理期间调用时，这将导致 SvelteKit 返回一个错误响应而不会调用 `handleError`。 确保您没有捕获抛出的错误，否则会阻止 SvelteKit 处理它。 <div class="ts-block"> ```dts function error(status: number, body: App.Error): never; ``` </div> <div class="ts-block"> ```dts function error( status: number, body?: { message: string; } extends App.Error ? App.Error | string | undefined : never ): never; ``` </div> ## fail 创建一个 `ActionFailure` 对象。 <div class="ts-block"> ```dts function fail(status: number): ActionFailure<undefined>; ``` </div> <div class="ts-block"> ```dts function fail< T extends Record<string, unknown> | undefined = undefined >(status: number, data: T): ActionFailure<T>; ``` </div> ## isActionFailure 检查这是否是由 `fail` 抛出的 action 失败。 <div class="ts-block"> ```dts function isActionFailure(e: unknown): e is ActionFailure; ``` </div> ## isHttpError 检查这是否是由 `error` 抛出的错误。 <div class="ts-block"> ```dts function isHttpError<T extends number>( e: unknown, status?: T | undefined ): e is HttpError_1 & { status: T extends undefined ? never : T; }; ``` </div> ## isRedirect 检查这是否是由 `redirect` 抛出的重定向。 <div class="ts-block"> ```dts function isRedirect(e: unknown): e is Redirect_1; ``` </div> ## json 从提供的数据创建一个 JSON `Response` 对象。 <div class="ts-block"> ```dts function json( data: any, init?: ResponseInit | undefined ): Response; ``` </div> ## redirect 重定向一个请求。在请求处理期间调用时，SvelteKit 将返回一个重定向响应。确保您没有捕获抛出的重定向，否则会阻止 SvelteKit 处理它。 <div class="ts-block"> ```dts function redirect( status: | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | ({} & number), location: string | URL ): never; ``` </div> ## text 从提供的正文创建一个 `Response` 对象。 <div class="ts-block"> ```dts function text( body: string, init?: ResponseInit | undefined ): Response; ``` </div> ## Action 位于 `+page.server.js` 的 `export const actions = {..}` 中的表单 action 方法的形状。 更多信息请参见 [表单 action ](/docs/kit/form-actions)。 <div class="ts-block"> ```dts type Action< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, OutputData extends Record<string, any> | void = Record< string, any > | void, RouteId extends string | null = string | null > = ( event: RequestEvent<Params, RouteId> ) => MaybePromise<OutputData>; ``` </div> ## ActionFailure <div class="ts-block"> ```dts interface ActionFailure< T extends Record<string, unknown> | undefined = undefined > {/*…*/} ``` <div class="ts-block-property"> ```dts status: number; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts data: T; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts [uniqueSymbol]: true; ``` <div class="ts-block-property-details"></div> </div></div> ## ActionResult 通过 `fetch` 调用表单 action 时，响应将具有以下形状之一。 ```svelte <form method="post" use:enhance={() => { return ({ result }) => { // result is of type ActionResult }; }} ``` <div class="ts-block"> ```dts type ActionResult< Success extends | Record<string, unknown> | undefined = Record<string, any>, Failure extends | Record<string, unknown> | undefined = Record<string, any> > = | { type: 'success'; status: number; data?: Success } | { type: 'failure'; status: number; data?: Failure } | { type: 'redirect'; status: number; location: string } | { type: 'error'; status?: number; error: any }; ``` </div> ## Actions 位于 `+page.server.js` 的 `export const actions = {..}` 中的表单 action 方法的形状。更多信息请参见 [表单 action ](/docs/kit/form-actions)。 <div class="ts-block"> ```dts type Actions< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, OutputData extends Record<string, any> | void = Record< string, any > | void, RouteId extends string | null = string | null > = Record<string, Action<Params, OutputData, RouteId>>; ``` </div> ## Adapter [适配器](/docs/kit/adapters) 负责将生产构建转换为可以部署到您选择的平台的形式。 <div class="ts-block"> ```dts interface Adapter {/*…*/} ``` <div class="ts-block-property"> ```dts name: string; ``` <div class="ts-block-property-details"> 适配器的名称，用于记录。通常对应于包名称。 </div> </div> <div class="ts-block-property"> ```dts adapt(builder: Builder): MaybePromise<void>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `builder` 由 SvelteKit 提供的对象，包含适配应用的各种方法 </div> 此函数在 SvelteKit 构建您的应用之后调用。 </div> </div> <div class="ts-block-property"> ```dts supports?: {/*…*/} ``` <div class="ts-block-property-details"> 在开发和构建期间调用的检查，以确定此适配器的特定功能是否将在生产中工作。 <div class="ts-block-property-children"><div class="ts-block-property"> ```dts read?: (details: { config: any; route: { id: string } }) => boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `config` 合并后的路由配置 </div> 测试 `read` 是否支持来自 `$app/server` 的内容 </div> </div></div> </div> </div> <div class="ts-block-property"> ```dts emulate?(): MaybePromise<Emulator>; ``` <div class="ts-block-property-details"> 创建一个 `Emulator`，允许适配器在开发、构建和预渲染期间影响环境。 </div> </div></div> ## AfterNavigate 传递给 [`afterNavigate`](/docs/kit/$app-navigation#afterNavigate) 回调的参数。 <div class="ts-block"> ```dts interface AfterNavigate extends Omit<Navigation, 'type'> {/*…*/} ``` <div class="ts-block-property"> ```dts type: Exclude<NavigationType, 'leave'>; ``` <div class="ts-block-property-details"> 导航的类型： - `enter`：应用已水合 - `form`：用户提交了一个 `<form>` - `link`：导航由链接点击触发 - `goto`：导航由 `goto(...)` 调用或重定向触发 - `popstate`：导航由后退/前进导航触发 </div> </div> <div class="ts-block-property"> ```dts willUnload: false; ``` <div class="ts-block-property-details"> 由于 `afterNavigate` 回调在导航完成后调用，因此它们永远不会与卸载页面的导航一起调用。 </div> </div></div> ## AwaitedActions <div class="ts-block"> ```dts type AwaitedActions< T extends Record<string, (...args: any) => any> > = OptionalUnion< { [Key in keyof T]: UnpackValidationError< Awaited<ReturnType<T[Key]>> >; }[keyof T] >; ``` </div> ## BeforeNavigate 传递给 [`beforeNavigate`](/docs/kit/$app-navigation#beforeNavigate) 回调的参数。 <div class="ts-block"> ```dts interface BeforeNavigate extends Navigation {/*…*/} ``` <div class="ts-block-property"> ```dts cancel(): void; ``` <div class="ts-block-property-details"> 调用此方法以阻止导航的开始。 </div> </div></div> ## Builder 此对象传递给适配器的 `adapt` 函数。 它包含各种用于适配应用的方法和属性。 <div class="ts-block"> ```dts interface Builder {/*…*/} ``` <div class="ts-block-property"> ```dts log: Logger; ``` <div class="ts-block-property-details"> 将消息打印到控制台。除非 Vite 的 `logLevel` 为 `info`，否则 `log.info` 和 `log.minor` 是静默的。 </div> </div> <div class="ts-block-property"> ```dts rimraf(dir: string): void; ``` <div class="ts-block-property-details"> 移除 `dir` 及其所有内容。 </div> </div> <div class="ts-block-property"> ```dts mkdirp(dir: string): void; ``` <div class="ts-block-property-details"> 创建 `dir` 及其任何所需的父目录。 </div> </div> <div class="ts-block-property"> ```dts config: ValidatedConfig; ``` <div class="ts-block-property-details"> 完全解析的 `svelte.config.js`。 </div> </div> <div class="ts-block-property"> ```dts prerendered: Prerendered; ``` <div class="ts-block-property-details"> 预渲染页面和资产的信息（如果有的话）。 </div> </div> <div class="ts-block-property"> ```dts routes: RouteDefinition[]; ``` <div class="ts-block-property-details"> 所有路由的数组（包括预渲染的） </div> </div> <div class="ts-block-property"> ```dts createEntries(fn: (route: RouteDefinition) => AdapterEntry): Promise<void>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `fn` 将一组路由分组为一个入口点的函数 - <span class="tag deprecated">已弃用</span> 使用 `builder.routes` 代替 </div> 创建映射到应用一个或多个路由的独立函数。 </div> </div> <div class="ts-block-property"> ```dts findServerAssets(routes: RouteDefinition[]): string[]; ``` <div class="ts-block-property-details"> 查找属于 `routes` 的服务器文件导入的所有资产 </div> </div> <div class="ts-block-property"> ```dts generateFallback(dest: string): Promise<void>; ``` <div class="ts-block-property-details"> 为静态网页服务器生成一个回退页面，以在没有匹配路由时使用。适用于单页应用。 </div> </div> <div class="ts-block-property"> ```dts generateEnvModule(): void; ``` <div class="ts-block-property-details"> 生成一个模块，将构建时的环境变量暴露为 `$env/dynamic/public`。 </div> </div> <div class="ts-block-property"> ```dts generateManifest(opts: { relativePath: string; routes?: RouteDefinition[] }): string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `opts` 应用的基目录的相对路径，并可选择指定（esm 或 cjs）生成清单的格式 </div> 生成一个服务器端清单，用于初始化 SvelteKit 的 [服务器](/docs/kit/@sveltejs-kit#Server)。 </div> </div> <div class="ts-block-property"> ```dts getBuildDirectory(name: string): string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `name` 文件的路径，相对于构建目录 </div> 解析 `outDir` 内 `name` 目录的路径，例如 `/path/to/.svelte-kit/my-adapter`。 </div> </div> <div class="ts-block-property"> ```dts getClientDirectory(): string; ``` <div class="ts-block-property-details"> 获取包含客户端资产的目录的完全解析路径，包括您的 `static` 目录的内容。 </div> </div> <div class="ts-block-property"> ```dts getServerDirectory(): string; ``` <div class="ts-block-property-details"> 获取包含服务器端代码的目录的完全解析路径。 </div> </div> <div class="ts-block-property"> ```dts getAppPath(): string; ``` <div class="ts-block-property-details"> 获取包括任何配置的 `base` 路径的应用路径，例如 `my-base-path/_app`。 </div> </div> <div class="ts-block-property"> ```dts writeClient(dest: string): string[]; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `dest` 目标文件夹 - <span class="tag">返回</span> 写入 `dest` 的文件数组 </div> 将客户端资产写入 `dest`。 </div> </div> <div class="ts-block-property"> ```dts writePrerendered(dest: string): string[]; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `dest` 目标文件夹 - <span class="tag">返回</span> 写入 `dest` 的文件数组 </div> 将预渲染的文件写入 `dest`。 </div> </div> <div class="ts-block-property"> ```dts writeServer(dest: string): string[]; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `dest` 目标文件夹 - <span class="tag">返回</span> 写入 `dest` 的文件数组 </div> 将服务器端代码写入 `dest`。 </div> </div> <div class="ts-block-property"> ```dts copy( from: string, to: string, opts?: { filter?(basename: string): boolean; replace?: Record<string, string>; } ): string[]; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `from` 源文件或目录 - `to` 目标文件或目录 - `opts.filter` 一个函数，用于确定是否应该复制文件或目录 - `opts.replace` 一个字符串替换映射 - <span class="tag">返回</span> 被复制的文件数组 </div> 复制一个文件或目录。 </div> </div> <div class="ts-block-property"> ```dts compress(directory: string): Promise<void>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `directory` 包含要压缩文件的目录 </div> 使用 gzip 和 brotli 压缩 `directory` 中的文件（在适当情况下）。在原始文件旁边生成 `.gz` 和 `.br` 文件。 </div> </div></div> ## ClientInit <blockquote class="since note"> 自 2.10.0 起可用 </blockquote> [`init`](/docs/kit/hooks#Shared-hooks-init) 将在应用在浏览器中启动后调用一次。 <div class="ts-block"> ```dts type ClientInit = () => MaybePromise<void>; ``` </div> ## Config 有关详细信息，请参见[配置参考](/docs/kit/configuration)。 ## Cookies <div class="ts-block"> ```dts interface Cookies {/*…*/} ``` <div class="ts-block-property"> ```dts get(name: string, opts?: import('cookie').CookieParseOptions): string | undefined; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `name` cookie 的名称 - `opts` 选项，直接传递给 `cookie.parse`。请参阅 [文档](https://github.com/jshttp/cookie#cookieparsestr-options) </div> 获取以前用 `cookies.set` 设置的 cookie，或来自请求头的 cookie。 </div> </div> <div class="ts-block-property"> ```dts getAll(opts?: import('cookie').CookieParseOptions): Array<{ name: string; value: string }>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `opts` 选项，直接传递给 `cookie.parse`。请参阅 [文档](https://github.com/jshttp/cookie#cookieparsestr-options) </div> 获取以前用 `cookies.set` 设置的所有 cookie，或来自请求头的 cookie。 </div> </div> <div class="ts-block-property"> ```dts set( name: string, value: string, opts: import('cookie').CookieSerializeOptions & { path: string } ): void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `name` cookie 的名称 - `value` cookie 的值 - `opts` 选项，直接传递给 `cookie.serialize`。请参阅 [文档](https://github.com/jshttp/cookie#cookieserializename-value-options) </div> 设置一个 cookie。这将向响应添加一个 `set-cookie` 头，但也会使 cookie 在当前请求期间通过 `cookies.get` 或 `cookies.getAll` 可用。 `httpOnly` 和 `secure` 选项默认值为 `true`（除非在 http://localhost 上，`secure` 为 `false`），如果您希望 cookie 可以被客户端 JavaScript 读取和/或通过 HTTP 传输，必须显式禁用它们。`sameSite` 选项默认为 `lax`。 您必须为 cookie 指定一个 `path`。在大多数情况下，您应该明确设置 `path: '/'` 以使 cookie 在整个应用中可用。您可以使用相对路径，或者设置 `path: ''` 仅使 cookie 在当前路径及其子路径中可用。 </div> </div> <div class="ts-block-property"> ```dts delete(name: string, opts: import('cookie').CookieSerializeOptions & { path: string }): void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `name` cookie 的名称 - `opts` 选项，直接传递给 `cookie.serialize`。`path` 必须匹配您想要删除的 cookie 的路径。请参阅 [文档](https://github.com/jshttp/cookie#cookieserializename-value-options) </div> 通过将其值设为空字符串并将过期日期设为过去，删除一个 cookie。 您必须为 cookie 指定一个 `path`。在大多数情况下，您应该明确设置 `path: '/'` 以使 cookie 在整个应用中可用。您可以使用相对路径，或者设置 `path: ''` 仅使 cookie 在当前路径及其子路径中可用。 </div> </div> <div class="ts-block-property"> ```dts serialize( name: string, value: string, opts: import('cookie').CookieSerializeOptions & { path: string } ): string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `name` cookie 的名称 - `value` cookie 的值 - `opts` 选项，直接传递给 `cookie.serialize`。请参阅 [文档](https://github.com/jshttp/cookie#cookieserializename-value-options) </div> 将 cookie 名称-值对序列化为 `Set-Cookie` 头字符串，但不应用于响应。 `httpOnly` 和 `secure` 选项默认值为 `true`（除非在 http://localhost 上，`secure` 为 `false`），如果您希望 cookie 可以被客户端 JavaScript 读取和/或通过 HTTP 传输，必须显式禁用它们。`sameSite` 选项默认为 `lax`。 您必须为 cookie 指定一个 `path`。在大多数情况下，您应该明确设置 `path: '/'` 以使 cookie 在整个应用中可用。您可以使用相对路径，或者设置 `path: ''` 仅使 cookie 在当前路径及其子路径中可用。 </div> </div></div> ## Emulator 一组在开发、构建和预渲染期间影响环境的函数集合。 <div class="ts-block"> ```dts interface Emulator {/*…*/} ``` <div class="ts-block-property"> ```dts platform?(details: { config: any; prerender: PrerenderOption }): MaybePromise<App.Platform>; ``` <div class="ts-block-property-details"> 一个函数，接收当前路由的 `config` 和 `prerender` 选项，并返回一个 `App.Platform` 对象。 </div> </div></div> ## Handle [`handle`](/docs/kit/hooks#Server-hooks-handle) 钩子在 SvelteKit 服务器每次接收到一个 [请求](/docs/kit/web-standards#Fetch-APIs-Request) 时运行，并确定 [响应](/docs/kit/web-standards#Fetch-APIs-Response)。 它接收一个表示请求的 `event` 对象和一个名为 `resolve` 的函数，该函数渲染路由并生成一个 `Response`。 这允许您修改响应头或主体，或完全绕过 SvelteKit（例如，用于以编程方式实现路由）。 <div class="ts-block"> ```dts type Handle = (input: { event: RequestEvent; resolve( event: RequestEvent, opts?: ResolveOptions ): MaybePromise<Response>; }) => MaybePromise<Response>; ``` </div> ## HandleClientError 客户端 [`handleError`](/docs/kit/hooks#Shared-hooks-handleError) 钩子在导航过程中抛出意外错误时运行。 如果在加载或随后的渲染过程中抛出意外错误，此函数将使用错误和事件调用。 确保此函数 _永远_ 不会抛出错误。 <div class="ts-block"> ```dts type HandleClientError = (input: { error: unknown; event: NavigationEvent; status: number; message: string; }) => MaybePromise<void | App.Error>; ``` </div> ## HandleFetch [`handleFetch`](/docs/kit/hooks#Server-hooks-handleFetch) 钩子允许您修改（或替换）在服务器上运行的 `load` 函数中发生的 `fetch` 请求（或在预渲染期间）。 <div class="ts-block"> ```dts type HandleFetch = (input: { event: RequestEvent; request: Request; fetch: typeof fetch; }) => MaybePromise<Response>; ``` </div> ## HandleServerError 服务器端 [`handleError`](/docs/kit/hooks#Shared-hooks-handleError) 钩子在响应请求时抛出意外错误时运行。 如果在加载或渲染过程中抛出意外错误，此函数将使用错误和事件调用。 确保此函数 _永远_ 不会抛出错误。 <div class="ts-block"> ```dts type HandleServerError = (input: { error: unknown; event: RequestEvent; status: number; message: string; }) => MaybePromise<void | App.Error>; ``` </div> ## HttpError [`error`](/docs/kit/@sveltejs-kit#error) 函数返回的对象。 <div class="ts-block"> ```dts interface HttpError {/*…*/} ``` <div class="ts-block-property"> ```dts status: number; ``` <div class="ts-block-property-details"> [HTTP 状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses)，范围在 400-599 之间。 </div> </div> <div class="ts-block-property"> ```dts body: App.Error; ``` <div class="ts-block-property-details"> 错误的内容。 </div> </div></div> ## KitConfig 有关详细信息，请参见[配置参考](/docs/kit/configuration)。 ## LessThan <div class="ts-block"> ```dts type LessThan< TNumber extends number, TArray extends any[] = [] > = TNumber extends TArray['length'] ? TArray[number] : LessThan<TNumber, [...TArray, TArray['length']]>; ``` </div> ## Load `PageLoad` 和 `LayoutLoad` 的通用形式。您应该从 `./$types` 导入它们（参见[生成的类型](/docs/kit/types#Generated-types)），而不是直接使用 `Load`。 <div class="ts-block"> ```dts type Load< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, InputData extends Record<string, unknown> | null = Record< string, any > | null, ParentData extends Record<string, unknown> = Record< string, any >, OutputData extends Record< string, unknown > | void = Record<string, any> | void, RouteId extends string | null = string | null > = ( event: LoadEvent<Params, InputData, ParentData, RouteId> ) => MaybePromise<OutputData>; ``` </div> ## LoadEvent `PageLoadEvent` 和 `LayoutLoadEvent` 的通用形式。您应该从 `./$types` 导入它们（参见[生成的类型](/docs/kit/types#Generated-types)），而不是直接使用 `LoadEvent`。 <div class="ts-block"> ```dts interface LoadEvent< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, Data extends Record<string, unknown> | null = Record< string, any > | null, ParentData extends Record<string, unknown> = Record< string, any >, RouteId extends string | null = string | null > extends NavigationEvent<Params, RouteId> {/*…*/} ``` <div class="ts-block-property"> ```dts fetch: typeof fetch; ``` <div class="ts-block-property-details"> `fetch` 等同于 [原生 `fetch` Web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch)，具有一些附加功能： - 它可以在服务器上用于进行带凭证的请求，因为它继承了页面请求的 `cookie` 和 `authorization` 头。 - 它可以在服务器上进行相对请求（通常，`fetch` 在服务器上下文中使用时需要带有源的 URL）。 - 内部请求（例如，用于 `+server.js` 路由）在服务器上运行时直接进入处理函数，而无需 HTTP 调用的开销。 - 在服务器端渲染期间，通过钩入 `Response` 对象的 `text` 和 `json` 方法，响应将被捕获并内联到渲染的 HTML 中。注意，除非通过 [`filterSerializedResponseHeaders`](/docs/kit/hooks#Server-hooks-handle) 显式包含，否则头部将 _不会_ 被序列化。 - 在水合过程中，响应将从 HTML 中读取，确保一致性并防止额外的网络请求。 您可以在[这里](/docs/kit/load#Cookies)了解更多关于使用 cookies 进行带凭证请求的信息。 </div> </div> <div class="ts-block-property"> ```dts data: Data; ``` <div class="ts-block-property-details"> 包含路由的服务器 `load` 函数（在 `+layout.server.js` 或 `+page.server.js` 中）返回的数据（如果有）。 </div> </div> <div class="ts-block-property"> ```dts setHeaders(headers: Record<string, string>): void; ``` <div class="ts-block-property-details"> 如果您需要为响应设置头，可以使用此方法。这在您希望页面被缓存时特别有用，例如： ```js // @errors: 7031 /// file: src/routes/blog/+page.js export async function load({ fetch, setHeaders }) { const url = `https://cms.example.com/articles.json`; const response = await fetch(url); setHeaders({ age: response.headers.get('age'), 'cache-control': response.headers.get('cache-control') }); return response.json(); } ``` 在多个 `load` 函数中多次设置相同的头（即使在不同的 `load` 函数中）也是错误的——您只能设置每个头一次。 您不能使用 `setHeaders` 添加 `set-cookie` 头——请改用服务器端 `load` 函数中的 [`cookies`](/docs/kit/@sveltejs-kit#Cookies) API。 当 `load` 函数在浏览器中运行时，`setHeaders` 无效。 </div> </div> <div class="ts-block-property"> ```dts parent(): Promise<ParentData>; ``` <div class="ts-block-property-details"> `await parent()` 返回来自父级 `+layout.js` `load` 函数的数据。 隐式地，缺失 `+layout.js` 被视为一个 `({ data }) => data` 函数，这意味着它将返回并转发来自父级 `+layout.server.js` 文件的数据。 当使用 `await parent()` 时，请注意不要引入意外的瀑布。如果例如，您只想将父级数据合并到返回的输出中，请在获取其他数据后调用它。 </div> </div> <div class="ts-block-property"> ```dts depends(...deps: Array<`${string}:${string}`>): void; ``` <div class="ts-block-property-details"> 此函数声明 `load` 函数对一个或多个 URL 或自定义标识符有 _依赖_，这些依赖随后可以与 [`invalidate()`](/docs/kit/$app-navigation#invalidate) 一起使用，导致 `load` 函数重新运行。 大多数情况下您不需要这样做，因为 `fetch` 会代表您调用 `depends`——只有在您使用绕过 `fetch` 的自定义 API 客户端时才需要。 URL 可以是绝对的或相对于正在加载的页面，并且必须是[编码的](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding)。 自定义标识符必须以一个或多个小写字母后跟冒号作为前缀，以符合 [URI 规范](https://www.rfc-editor.org/rfc/rfc3986.html)。 以下示例展示了如何使用 `depends` 注册对一个自定义标识符的依赖，该标识符在按钮点击后被 `invalidate`，使得 `load` 函数重新运行。 ```js // @errors: 7031 /// file: src/routes/+page.js let count = 0; export async function load({ depends }) { depends('increase:count'); return { count: count++ }; } ``` ```html /// file: src/routes/+page.svelte <script> import { invalidate } from '$app/navigation'; let { data } = $props(); const increase = async () => { await invalidate('increase:count'); }; </script> <p>{data.count}</p> <p> <button on:click="{increase}">Increase Count</button> </p> ``` </div> </div> <div class="ts-block-property"> ```dts untrack<T>(fn: () => T): T; ``` <div class="ts-block-property-details"> 使用此函数可选择退出依赖跟踪，针对在回调中同步调用的所有内容。例如： ```js // @errors: 7031 /// file: src/routes/+page.server.js export async function load({ untrack, url }) { // 取消跟踪 url.pathname，以便路径更改不会触发重新运行 if (untrack(() => url.pathname === '/')) { return { message: 'Welcome!' }; } } ``` </div> </div></div> ## LoadProperties <div class="ts-block"> ```dts type LoadProperties< input extends Record<string, any> | void > = input extends void ? undefined // needs to be undefined, because void will break intellisense : input extends Record<string, any> ? input : unknown; ``` </div> ## Navigation <div class="ts-block"> ```dts interface Navigation {/*…*/} ``` <div class="ts-block-property"> ```dts from: NavigationTarget | null; ``` <div class="ts-block-property-details"> 导航的来源 </div> </div> <div class="ts-block-property"> ```dts to: NavigationTarget | null; ``` <div class="ts-block-property-details"> 导航的目标/已导航到的地方 </div> </div> <div class="ts-block-property"> ```dts type: Exclude<NavigationType, 'enter'>; ``` <div class="ts-block-property-details"> 导航的类型： - `form`：用户提交了一个 `<form>` - `leave`：应用正在离开，因为标签页正在关闭或导航到不同的文档 - `link`：导航由链接点击触发 - `goto`：导航由 `goto(...)` 调用或重定向触发 - `popstate`：导航由后退/前进导航触发 </div> </div> <div class="ts-block-property"> ```dts willUnload: boolean; ``` <div class="ts-block-property-details"> 导航是否会导致页面卸载（即不是客户端导航） </div> </div> <div class="ts-block-property"> ```dts delta?: number; ``` <div class="ts-block-property-details"> 在历史记录后退/前进导航的情况下，后退/前进的步骤数 </div> </div> <div class="ts-block-property"> ```dts complete: Promise<void>; ``` <div class="ts-block-property-details"> 一个在导航完成后解析的 promise，如果导航失败或被中止则拒绝。 在 `willUnload` 导航的情况下，promise 将永远不会解析。 </div> </div></div> ## NavigationEvent <div class="ts-block"> ```dts interface NavigationEvent< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, RouteId extends string | null = string | null > {/*…*/} ``` <div class="ts-block-property"> ```dts params: Params; ``` <div class="ts-block-property-details"> 当前页面的参数，例如对于 `/blog/[slug]` 路由，一个 `{ slug: string }` 对象 </div> </div> <div class="ts-block-property"> ```dts route: {/*…*/} ``` <div class="ts-block-property-details"> 关于当前路由的信息 <div class="ts-block-property-children"><div class="ts-block-property"> ```dts id: RouteId; ``` <div class="ts-block-property-details"> 当前路由的 ID，例如对于 `src/routes/blog/[slug]`，它将是 `/blog/[slug]` </div> </div></div> </div> </div> <div class="ts-block-property"> ```dts url: URL; ``` <div class="ts-block-property-details"> 当前页面的 URL </div> </div></div> ## NavigationTarget 关于特定导航目标的信息。 <div class="ts-block"> ```dts interface NavigationTarget {/*…*/} ``` <div class="ts-block-property"> ```dts params: Record<string, string> | null; ``` <div class="ts-block-property-details"> 目标页面的参数，例如对于 `/blog/[slug]` 路由，一个 `{ slug: string }` 对象。 如果目标不是 SvelteKit 应用的一部分（无法解析为路由），则为 `null`。 </div> </div> <div class="ts-block-property"> ```dts route: { id: string | null }; ``` <div class="ts-block-property-details"> 目标路由的信息 </div> </div> <div class="ts-block-property"> ```dts url: URL; ``` <div class="ts-block-property-details"> 要导航到的 URL </div> </div></div> ## NavigationType - `enter`：应用已水合 - `form`：用户提交了一个带有 GET 方法的 `<form>` - `leave`：用户通过关闭标签页或使用后退/前进按钮导航到不同的文档而离开应用 - `link`：导航由链接点击触发 - `goto`：导航由 `goto(...)` 调用或重定向触发 - `popstate`：导航由后退/前进导航触发 <div class="ts-block"> ```dts type NavigationType = | 'enter' | 'form' | 'leave' | 'link' | 'goto' | 'popstate'; ``` </div> ## NumericRange <div class="ts-block"> ```dts type NumericRange< TStart extends number, TEnd extends number > = Exclude<TEnd | LessThan<TEnd>, LessThan<TStart>>; ``` </div> ## OnNavigate 传递给 [`onNavigate`](/docs/kit/$app-navigation#onNavigate) 回调的参数。 <div class="ts-block"> ```dts interface OnNavigate extends Navigation {/*…*/} ``` <div class="ts-block-property"> ```dts type: Exclude<NavigationType, 'enter' | 'leave'>; ``` <div class="ts-block-property-details"> 导航的类型： - `form`：用户提交了一个 `<form>` - `link`：导航由链接点击触发 - `goto`：导航由 `goto(...)` 调用或重定向触发 - `popstate`：导航由后退/前进导航触发 </div> </div> <div class="ts-block-property"> ```dts willUnload: false; ``` <div class="ts-block-property-details"> 由于 `onNavigate` 回调立即在客户端导航之前调用，它们永远不会与卸载页面的导航一起调用。 </div> </div></div> ## Page `$page` store 的形状 <div class="ts-block"> ```dts interface Page< Params extends Record<string, string> = Record< string, string >, RouteId extends string | null = string | null > {/*…*/} ``` <div class="ts-block-property"> ```dts url: URL; ``` <div class="ts-block-property-details"> 当前页面的 URL </div> </div> <div class="ts-block-property"> ```dts params: Params; ``` <div class="ts-block-property-details"> 当前页面的参数，例如对于 `/blog/[slug]` 路由，一个 `{ slug: string }` 对象 </div> </div> <div class="ts-block-property"> ```dts route: {/*…*/} ``` <div class="ts-block-property-details"> 关于当前路由的信息 <div class="ts-block-property-children"><div class="ts-block-property"> ```dts id: RouteId; ``` <div class="ts-block-property-details"> 当前路由的 ID，例如对于 `src/routes/blog/[slug]`，它将是 `/blog/[slug]` </div> </div></div> </div> </div> <div class="ts-block-property"> ```dts status: number; ``` <div class="ts-block-property-details"> 当前页面的 HTTP 状态码 </div> </div> <div class="ts-block-property"> ```dts error: App.Error | null; ``` <div class="ts-block-property-details"> 当前页面的错误对象（如果有的话）。来自 `handleError` 钩子填充。 </div> </div> <div class="ts-block-property"> ```dts data: App.PageData & Record<string, any>; ``` <div class="ts-block-property-details"> 当前页面所有 `load` 函数的数据的合并结果。您可以通过 `App.PageData` 类型一个共同的分母。 </div> </div> <div class="ts-block-property"> ```dts state: App.PageState; ``` <div class="ts-block-property-details"> 页面状态，可以通过 `$app/navigation` 的 [`pushState`](/docs/kit/$app-navigation#pushState) 和 [`replaceState`](/docs/kit/$app-navigation#replaceState) 函数进行操作。 </div> </div> <div class="ts-block-property"> ```dts form: any; ``` <div class="ts-block-property-details"> 仅在表单提交后填充。更多信息请参见 [表单 action ](/docs/kit/form-actions)。 </div> </div></div> ## ParamMatcher 参数匹配器的形状。更多信息请参见 [匹配](/docs/kit/advanced-routing#Matching)。 <div class="ts-block"> ```dts type ParamMatcher = (param: string) => boolean; ``` </div> ## PrerenderOption <div class="ts-block"> ```dts type PrerenderOption = boolean | 'auto'; ``` </div> ## Redirect [`redirect`](/docs/kit/@sveltejs-kit#redirect) 函数返回的对象 <div class="ts-block"> ```dts interface Redirect {/*…*/} ``` <div class="ts-block-property"> ```dts status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308; ``` <div class="ts-block-property-details"> [HTTP 状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages)，范围在 300-308 之间。 </div> </div> <div class="ts-block-property"> ```dts location: string; ``` <div class="ts-block-property-details"> 要重定向到的位置。 </div> </div></div> ## RequestEvent <div class="ts-block"> ```dts interface RequestEvent< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, RouteId extends string | null = string | null > {/*…*/} ``` <div class="ts-block-property"> ```dts cookies: Cookies; ``` <div class="ts-block-property-details"> 获取或设置与当前请求相关的 cookie </div> </div> <div class="ts-block-property"> ```dts fetch: typeof fetch; ``` <div class="ts-block-property-details"> `fetch` 等同于 [原生 `fetch` Web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch)，具有一些附加功能： - 它可以在服务器上用于进行带凭证的请求，因为它继承了页面请求的 `cookie` 和 `authorization` 头。 - 它可以在服务器上进行相对请求（通常，`fetch` 在服务器上下文中使用时需要带有源的 URL）。 - 内部请求（例如，用于 `+server.js` 路由）在服务器上运行时直接进入处理函数，而无需 HTTP 调用的开销。 - 在服务器端渲染期间，通过钩入 `Response` 对象的 `text` 和 `json` 方法，响应将被捕获并内联到渲染的 HTML 中。注意，除非通过 [`filterSerializedResponseHeaders`](/docs/kit/hooks#Server-hooks-handle) 显式包含，否则头部将 _不会_ 被序列化。 - 在水合过程中，响应将从 HTML 中读取，确保一致性并防止额外的网络请求。 您可以在[这里](/docs/kit/load#Cookies)了解更多关于使用 cookies 进行带凭证请求的信息。 </div> </div> <div class="ts-block-property"> ```dts getClientAddress(): string; ``` <div class="ts-block-property-details"> 客户端的 IP 地址，由适配器设置。 </div> </div> <div class="ts-block-property"> ```dts locals: App.Locals; ``` <div class="ts-block-property-details"> 包含在 [`server handle hook`](/docs/kit/hooks#Server-hooks-handle) 中向请求添加的自定义数据。 </div> </div> <div class="ts-block-property"> ```dts params: Params; ``` <div class="ts-block-property-details"> 当前路由的参数，例如对于 `/blog/[slug]` 路由，一个 `{ slug: string }` 对象 </div> </div> <div class="ts-block-property"> ```dts platform: Readonly<App.Platform> | undefined; ``` <div class="ts-block-property-details"> 通过适配器提供的额外数据。 </div> </div> <div class="ts-block-property"> ```dts request: Request; ``` <div class="ts-block-property-details"> 原始请求对象 </div> </div> <div class="ts-block-property"> ```dts route: {/*…*/} ``` <div class="ts-block-property-details"> 关于当前路由的信息 <div class="ts-block-property-children"><div class="ts-block-property"> ```dts id: RouteId; ``` <div class="ts-block-property-details"> 当前路由的 ID，例如对于 `src/routes/blog/[slug]`，它将是 `/blog/[slug]` </div> </div></div> </div> </div> <div class="ts-block-property"> ```dts setHeaders(headers: Record<string, string>): void; ``` <div class="ts-block-property-details"> 如果您需要为响应设置头，可以使用此方法。这在您希望页面被缓存时特别有用，例如： ```js // @errors: 7031 /// file: src/routes/blog/+page.js export async function load({ fetch, setHeaders }) { const url = `https://cms.example.com/articles.json`; const response = await fetch(url); setHeaders({ age: response.headers.get('age'), 'cache-control': response.headers.get('cache-control') }); return response.json(); } ``` 在多个 `load` 函数中多次设置相同的头（即使在不同的 `load` 函数中）也是错误的——您只能设置每个头一次。 您不能使用 `setHeaders` 添加 `set-cookie` 头——请改用服务器端 `load` 函数中的 [`cookies`](/docs/kit/@sveltejs-kit#Cookies) API。 </div> </div> <div class="ts-block-property"> ```dts url: URL; ``` <div class="ts-block-property-details"> 请求的 URL。 </div> </div> <div class="ts-block-property"> ```dts isDataRequest: boolean; ``` <div class="ts-block-property-details"> 如果请求来自客户端询问 `+page/layout.server.js` 数据，则为 `true`。在这种情况下，`url` 属性将被移除与数据请求相关的内部信息。 如果这种区别对您很重要，请使用此属性。 </div> </div> <div class="ts-block-property"> ```dts isSubRequest: boolean; ``` <div class="ts-block-property-details"> 如果请求是来自 SvelteKit 的 `+server.js` 调用，则为 `true`，无需实际进行 HTTP 请求。这发生在服务器上进行同源 `fetch` 请求时。 </div> </div></div> ## RequestHandler 一个从 `+server.js` 文件导出的 `(event: RequestEvent) => Response` 函数，它对应于一个 HTTP 动词 (`GET`, `PUT`, `PATCH` 等)，并处理具有该方法的请求。 它接收 `Params` 作为第一个泛型参数，您可以通过使用 [生成的类型](/docs/kit/types#Generated-types) 来跳过它。 <div class="ts-block"> ```dts type RequestHandler< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, RouteId extends string | null = string | null > = ( event: RequestEvent<Params, RouteId> ) => MaybePromise<Response>; ``` </div> ## Reroute <blockquote class="since note"> 自 2.3.0 起可用 </blockquote> [`reroute`](/docs/kit/hooks#Universal-hooks-reroute) 钩子允许您在用于确定要渲染哪个路由之前修改 URL。 <div class="ts-block"> ```dts type Reroute = (event: { url: URL }) => void | string; ``` </div> ## ResolveOptions <div class="ts-block"> ```dts interface ResolveOptions {/*…*/} ``` <div class="ts-block-property"> ```dts transformPageChunk?(input: { html: string; done: boolean }): MaybePromise<string | undefined>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `input` html 块和是否是最后一个块的信息 </div> 对 HTML 进行自定义转换。如果 `done` 为 true，则是最后一个块。块不保证是完整的 HTML（例如，它们可能包含一个元素的开始标签但不包含结束标签），但它们总是会在诸如 `%sveltekit.head%` 或布局/页面组件等合理的边界处拆分。 </div> </div> <div class="ts-block-property"> ```dts filterSerializedResponseHeaders?(name: string, value: string): boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `name` 头名称 - `value` 头值 </div> 确定在 `load` 函数使用 `fetch` 加载资源时，哪些头应包含在序列化的响应中。 默认情况下，不会包含任何头。 </div> </div> <div class="ts-block-property"> ```dts preload?(input: { type: 'font' | 'css' | 'js' | 'asset'; path: string }): boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - `input` 文件的类型和路径 </div> 确定应添加到 `<head>` 标签以预加载的内容。 默认情况下，`js` 和 `css` 文件将被预加载。 </div> </div></div> ## RouteDefinition <div class="ts-block"> ```dts interface RouteDefinition<Config = any> {/*…*/} ``` <div class="ts-block-property"> ```dts id: string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts api: { methods: Array<HttpMethod | '*'>; }; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts page: { methods: Array<Extract<HttpMethod, 'GET' | 'POST'>>; }; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts pattern: RegExp; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts prerender: PrerenderOption; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts segments: RouteSegment[]; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts methods: Array<HttpMethod | '*'>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts config: Config; ``` <div class="ts-block-property-details"></div> </div></div> ## SSRManifest <div class="ts-block"> ```dts interface SSRManifest {/*…*/} ``` <div class="ts-block-property"> ```dts appDir: string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts appPath: string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts assets: Set<string>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts mimeTypes: Record<string, string>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts _: {/*…*/} ``` <div class="ts-block-property-details"> 私有字段 <div class="ts-block-property-children"><div class="ts-block-property"> ```dts client: NonNullable<BuildData['client']>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts nodes: SSRNodeLoader[]; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts routes: SSRRoute[]; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts matchers(): Promise<Record<string, ParamMatcher>>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts server_assets: Record<string, number>; ``` <div class="ts-block-property-details"> 所有由服务器代码导入的资产的 `[file]: size` 映射 </div> </div></div> </div> </div></div> ## ServerInit <blockquote class="since note"> 自 2.10.0 起可用 </blockquote> [`init`](/docs/kit/hooks#Shared-hooks-init) 将在服务器响应其第一个请求之前调用。 <div class="ts-block"> ```dts type ServerInit = () => MaybePromise<void>; ``` </div> ## ServerInitOptions <div class="ts-block"> ```dts interface ServerInitOptions {/*…*/} ``` <div class="ts-block-property"> ```dts env: Record<string, string>; ``` <div class="ts-block-property-details"> 环境变量的映射 </div> </div> <div class="ts-block-property"> ```dts read?: (file: string) => ReadableStream; ``` <div class="ts-block-property-details"> 一个将资产文件名转换为 `ReadableStream` 的函数。对于 `$app/server` 的 `read` 导出，这个是必需的。 </div> </div></div> ## ServerLoad `PageServerLoad` 和 `LayoutServerLoad` 的通用形式。您应该从 `./$types` 导入它们（参见[生成的类型](/docs/kit/types#Generated-types)），而不是直接使用 `ServerLoad`。 <div class="ts-block"> ```dts type ServerLoad< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, ParentData extends Record<string, any> = Record< string, any >, OutputData extends Record<string, any> | void = Record< string, any > | void, RouteId extends string | null = string | null > = ( event: ServerLoadEvent<Params, ParentData, RouteId> ) => MaybePromise<OutputData>; ``` </div> ## ServerLoadEvent <div class="ts-block"> ```dts interface ServerLoadEvent< Params extends Partial<Record<string, string>> = Partial< Record<string, string> >, ParentData extends Record<string, any> = Record< string, any >, RouteId extends string | null = string | null > extends RequestEvent<Params, RouteId> {/*…*/} ``` <div class="ts-block-property"> ```dts parent(): Promise<ParentData>; ``` <div class="ts-block-property-details"> `await parent()` 返回来自父级 `+layout.server.js` `load` 函数的数据。 当使用 `await parent()` 时，请注意不要引入意外的瀑布。如果例如，您只想将父级数据合并到返回的输出中，请在获取其他数据后调用它。 </div> </div> <div class="ts-block-property"> ```dts depends(...deps: string[]): void; ``` <div class="ts-block-property-details"> 此函数声明 `load` 函数对一个或多个 URL 或自定义标识符有 _依赖_，这些依赖随后可以与 [`invalidate()`](/docs/kit/$app-navigation#invalidate) 一起使用，导致 `load` 函数重新运行。 大多数情况下您不需要这样做，因为 `fetch` 会代表您调用 `depends`——只有在您使用绕过 `fetch` 的自定义 API 客户端时才需要。 URL 可以是绝对的或相对于正在加载的页面，并且必须是[编码的](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding)。 自定义标识符必须以一个或多个小写字母后跟冒号作为前缀，以符合 [URI 规范](https://www.rfc-editor.org/rfc/rfc3986.html)。 以下示例展示了如何使用 `depends` 注册对一个自定义标识符的依赖，该标识符在按钮点击后被 `invalidate`，使得 `load` 函数重新运行。 ```js // @errors: 7031 /// file: src/routes/+page.js let count = 0; export async function load({ depends }) { depends('increase:count'); return { count: count++ }; } ``` ```html /// file: src/routes/+page.svelte <script> import { invalidate } from '$app/navigation'; let { data } = $props(); const increase = async () => { await invalidate('increase:count'); }; </script> <p>{data.count}</p> <p> <button on:click="{increase}">Increase Count</button> </p> ``` </div> </div> <div class="ts-block-property"> ```dts untrack<T>(fn: () => T): T; ``` <div class="ts-block-property-details"> 使用此函数可选择退出依赖跟踪，针对在回调中同步调用的所有内容。例如： ```js // @errors: 7031 /// file: src/routes/+page.js export async function load({ untrack, url }) { // 取消跟踪 url.pathname，以便路径更改不会触发重新运行 if (untrack(() => url.pathname === '/')) { return { message: 'Welcome!' }; } } ``` </div> </div></div> ## Snapshot 导出自页面或布局组件的 `export const snapshot` 的类型。 <div class="ts-block"> ```dts interface Snapshot<T = any> {/*…*/} ``` <div class="ts-block-property"> ```dts capture: () => T; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts restore: (snapshot: T) => void; ``` <div class="ts-block-property-details"></div> </div></div> ## SubmitFunction <div class="ts-block"> ```dts type SubmitFunction< Success extends | Record<string, unknown> | undefined = Record<string, any>, Failure extends | Record<string, unknown> | undefined = Record<string, any> > = (input: { action: URL; formData: FormData; formElement: HTMLFormElement; controller: AbortController; submitter: HTMLElement | null; cancel(): void; }) => MaybePromise< | void | ((opts: { formData: FormData; formElement: HTMLFormElement; action: URL; result: ActionResult<Success, Failure>; /** * 调用此方法以获取表单提交响应的默认行为。 * @param options 如果不希望在成功提交后重置 `<form>` 的值，请设置 `reset: false`。 * @param invalidateAll 如果不希望在提交后调用 `invalidateAll`，请设置 `invalidateAll: false`。 */ update(options?: { reset?: boolean; invalidateAll?: boolean; }): Promise<void>; }) => void) >; ``` </div> ## Transport <blockquote class="since note"> 自 2.11.0 起可用 </blockquote> [`transport`](/docs/kit/hooks#Universal-hooks-transport) 钩子允许您在服务器/客户端边界上传输自定义类型。 每个传输器都有一对 `encode` 和 `decode` 函数。在服务器端，`encode` 决定一个值是否是自定义类型的实例，如果是，则返回该值的非假编码（可以是对象或数组，否则返回 `false`）。 在浏览器端，`decode` 将编码转换回自定义类型的实例。 ```ts import type { Transport } from '@sveltejs/kit'; declare class MyCustomType { data: any; } // hooks.js export const transport: Transport = { MyCustomType: { encode: (value) => value instanceof MyCustomType && [value.data], decode: ([data]) => new MyCustomType(data) } }; ``` <div class="ts-block"> ```dts type Transport = Record<string, Transporter>; ``` </div> ## Transporter [`transport`](/docs/kit/hooks#Universal-hooks-transport) 钩子的成员。 <div class="ts-block"> ```dts interface Transporter< T = any, U = Exclude< any, false | 0 | '' | null | undefined | typeof NaN > > {/*…*/} ``` <div class="ts-block-property"> ```dts encode: (value: T) => false | U; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts decode: (data: U) => T; ``` <div class="ts-block-property-details"></div> </div></div> ## Private types 以下类型由上面文档的公共类型引用，但不能直接导入： ## AdapterEntry <div class="ts-block"> ```dts interface AdapterEntry {/*…*/} ``` <div class="ts-block-property"> ```dts id: string; ``` <div class="ts-block-property-details"> 一个唯一标识 HTTP 服务（例如无服务器函数）的字符串，用于去重。 例如，`/foo/a-[b]` 和 `/foo/[c]` 是不同的路由，但在 Netlify `_redirects` 文件中都会表示为 `/foo/:param`，因此它们共享一个 ID </div> </div> <div class="ts-block-property"> ```dts filter(route: RouteDefinition): boolean; ``` <div class="ts-block-property-details"> 一个函数，用于比较候选路由与当前路由，以确定是否应与当前路由分组。 用例： - 回退页面：`/foo/[c]` 是 `/foo/a-[b]` 的回退，`/[...catchall]` 是所有路由的回退 - 分组共享通用 `config` 的路由：`/foo` 应部署到边缘，`/bar` 和 `/baz` 应部署到无服务器函数 </div> </div> <div class="ts-block-property"> ```dts complete(entry: { generateManifest(opts: { relativePath: string }): string }): MaybePromise<void>; ``` <div class="ts-block-property-details"> 一个在创建入口点后调用的函数。这是您应该将函数写入文件系统并生成重定向清单的地方。 </div> </div></div> ## Csp <div class="ts-block"> ```dts namespace Csp { type ActionSource = 'strict-dynamic' | 'report-sample'; type BaseSource = | 'self' | 'unsafe-eval' | 'unsafe-hashes' | 'unsafe-inline' | 'wasm-unsafe-eval' | 'none'; type CryptoSource = `${'nonce' | 'sha256' | 'sha384' | 'sha512'}-${string}`; type FrameSource = | HostSource | SchemeSource | 'self' | 'none'; type HostNameScheme = `${string}.${string}` | 'localhost'; type HostSource = `${HostProtocolSchemes}${HostNameScheme}${PortScheme}`; type HostProtocolSchemes = `${string}://` | ''; type HttpDelineator = '/' | '?' | '#' | '\\'; type PortScheme = `:${number}` | '' | ':*'; type SchemeSource = | 'http:' | 'https:' | 'data:' | 'mediastream:' | 'blob:' | 'filesystem:'; type Source = | HostSource | SchemeSource | CryptoSource | BaseSource; type Sources = Source[]; } ``` </div> ## CspDirectives <div class="ts-block"> ```dts interface CspDirectives {/*…*/} ``` <div class="ts-block-property"> ```dts 'child-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'default-src'?: Array<Csp.Source | Csp.ActionSource>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'frame-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'worker-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'connect-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'font-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'img-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'manifest-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'media-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'object-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'prefetch-src'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'script-src'?: Array<Csp.Source | Csp.ActionSource>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'script-src-elem'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'script-src-attr'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'style-src'?: Array<Csp.Source | Csp.ActionSource>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'style-src-elem'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'style-src-attr'?: Csp.Sources; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'base-uri'?: Array<Csp.Source | Csp.ActionSource>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts sandbox?: Array< | 'allow-downloads-without-user-activation' | 'allow-forms' | 'allow-modals' | 'allow-orientation-lock' | 'allow-pointer-lock' | 'allow-popups' | 'allow-popups-to-escape-sandbox' | 'allow-presentation' | 'allow-same-origin' | 'allow-scripts' | 'allow-storage-access-by-user-activation' | 'allow-top-navigation' | 'allow-top-navigation-by-user-activation' >; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'form-action'?: Array<Csp.Source | Csp.ActionSource>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'frame-ancestors'?: Array<Csp.HostSource | Csp.SchemeSource | Csp.FrameSource>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'navigate-to'?: Array<Csp.Source | Csp.ActionSource>; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'report-uri'?: string[]; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'report-to'?: string[]; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts 'require-trusted-types-for'?: Array<'script'>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">已弃用</span> </div> </div> </div> <div class="ts-block-property"> ```dts 'trusted-types'?: Array<'none' | 'allow-duplicates' | '*' | string>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">已弃用</span> </div> </div> </div> <div class="ts-block-property"> ```dts 'upgrade-insecure-requests'?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">已弃用</span> </div> </div> </div> <div class="ts-block-property"> ```dts 'require-sri-for'?: Array<'script' | 'style' | 'script style'>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag deprecated">已弃用</span> </div> </div> </div></div> ## HttpMethod <div class="ts-block"> ```dts type HttpMethod = | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS'; ``` </div> ## Logger <div class="ts-block"> ```dts interface Logger {/*…*/} ``` <div class="ts-block-property"> ```dts (msg: string): void; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts success(msg: string): void; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts error(msg: string): void; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts warn(msg: string): void; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts minor(msg: string): void; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts info(msg: string): void; ``` <div class="ts-block-property-details"></div> </div></div> ## MaybePromise <div class="ts-block"> ```dts type MaybePromise<T> = T | Promise<T>; ``` </div> ## PrerenderEntryGeneratorMismatchHandler <div class="ts-block"> ```dts interface PrerenderEntryGeneratorMismatchHandler {/*…*/} ``` <div class="ts-block-property"> ```dts (details: { generatedFromId: string; entry: string; matchedId: string; message: string }): void; ``` <div class="ts-block-property-details"></div> </div></div> ## PrerenderEntryGeneratorMismatchHandlerValue <div class="ts-block"> ```dts type PrerenderEntryGeneratorMismatchHandlerValue = | 'fail' | 'warn' | 'ignore' | PrerenderEntryGeneratorMismatchHandler; ``` </div> ## PrerenderHttpErrorHandler <div class="ts-block"> ```dts interface PrerenderHttpErrorHandler {/*…*/} ``` <div class="ts-block-property"> ```dts (details: { status: number; path: string; referrer: string | null; referenceType: 'linked' | 'fetched'; message: string; }): void; ``` <div class="ts-block-property-details"></div> </div></div> ## PrerenderHttpErrorHandlerValue <div class="ts-block"> ```dts type PrerenderHttpErrorHandlerValue = | 'fail' | 'warn' | 'ignore' | PrerenderHttpErrorHandler; ``` </div> ## PrerenderMap <div class="ts-block"> ```dts type PrerenderMap = Map<string, PrerenderOption>; ``` </div> ## PrerenderMissingIdHandler <div class="ts-block"> ```dts interface PrerenderMissingIdHandler {/*…*/} ``` <div class="ts-block-property"> ```dts (details: { path: string; id: string; referrers: string[]; message: string }): void; ``` <div class="ts-block-property-details"></div> </div></div> ## PrerenderMissingIdHandlerValue <div class="ts-block"> ```dts type PrerenderMissingIdHandlerValue = | 'fail' | 'warn' | 'ignore' | PrerenderMissingIdHandler; ``` </div> ## PrerenderOption <div class="ts-block"> ```dts type PrerenderOption = boolean | 'auto'; ``` </div> ## Prerendered <div class="ts-block"> ```dts interface Prerendered {/*…*/} ``` <div class="ts-block-property"> ```dts pages: Map< string, { /** 甲骨文文件在输出目录中的位置 */ file: string; } >; ``` <div class="ts-block-property-details"> 一个 `path` 到 `{ file }` 对象的映射，例如 `/foo` 对应 `foo.html`，而 `/bar/` 对应 `bar/index.html`。 </div> </div> <div class="ts-block-property"> ```dts assets: Map< string, { type: string; } >; ``` <div class="ts-block-property-details"> 一个 `path` 到 `{ type }` 对象的映射。 </div> </div> <div class="ts-block-property"> ```dts redirects: Map< string, { status: number; location: string; } >; ``` <div class="ts-block-property-details"> 预渲染期间遇到的重定向的映射。 </div> </div> <div class="ts-block-property"> ```dts paths: string[]; ``` <div class="ts-block-property-details"> 预渲染的路径数组（不带尾部斜杠，无论 `trailingSlash` 配置如何） </div> </div></div> ## RequestOptions <div class="ts-block"> ```dts interface RequestOptions {/*…*/} ``` <div class="ts-block-property"> ```dts getClientAddress(): string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts platform?: App.Platform; ``` <div class="ts-block-property-details"></div> </div></div> ## RouteSegment <div class="ts-block"> ```dts interface RouteSegment {/*…*/} ``` <div class="ts-block-property"> ```dts content: string; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts dynamic: boolean; ``` <div class="ts-block-property-details"></div> </div> <div class="ts-block-property"> ```dts rest: boolean; ``` <div class="ts-block-property-details"></div> </div></div> ## TrailingSlash <div class="ts-block"> ```dts type TrailingSlash = 'never' | 'always' | 'ignore'; ``` </div> # @sveltejs/kit/hooks ```js // @noErrors import { sequence } from '@sveltejs/kit/hooks'; ``` ## sequence 一个用于以中间件方式顺序执行多个 `handle` 调用的辅助函数。 `handle` 选项的行为如下： - `transformPageChunk` 按相反顺序应用并合并 - `preload` 按正向顺序应用，第一个选项"获胜"，之后的 `preload` 选项不会被调用 - `filterSerializedResponseHeaders` 的行为与 `preload` 相同 ```js // @errors: 7031 /// file: src/hooks.server.js import { sequence } from '@sveltejs/kit/hooks'; /** @type {import('@sveltejs/kit').Handle} */ async function first({ event, resolve }) { console.log('第一个预处理'); const result = await resolve(event, { transformPageChunk: ({ html }) => { // 转换按相反顺序应用 console.log('第一个转换'); return html; }, preload: () => { // 这个会获胜，因为它是链中第一个定义的 console.log('第一个预加载'); return true; } }); console.log('第一个后处理'); return result; } /** @type {import('@sveltejs/kit').Handle} */ async function second({ event, resolve }) { console.log('第二个预处理'); const result = await resolve(event, { transformPageChunk: ({ html }) => { console.log('第二个转换'); return html; }, preload: () => { console.log('第二个预加载'); return true; }, filterSerializedResponseHeaders: () => { // 这个会获胜，因为它是链中第一个定义的 console.log('第二个序列化响应头过滤'); return true; } }); console.log('第二个后处理'); return result; } export const handle = sequence(first, second); ``` 上面的示例会打印： ``` 第一个预处理 第一个预加载 第二个预处理 第二个序列化响应头过滤 第二个转换 第一个转换 第二个后处理 第一个后处理 ``` <div class="ts-block"> ```dts function sequence( ...handlers: import('@sveltejs/kit').Handle[] ): import('@sveltejs/kit').Handle; ``` </div> # @sveltejs/kit/node/polyfills ```js // @noErrors import { installPolyfills } from '@sveltejs/kit/node/polyfills'; ``` ## installPolyfills 将以下 Web API 作为全局变量可用： - `crypto` - `File` <div class="ts-block"> ```dts function installPolyfills(): void; ``` </div> # @sveltejs/kit/node ```js // @noErrors import { createReadableStream, getRequest, setResponse } from '@sveltejs/kit/node'; ``` ## createReadableStream <blockquote class="since note"> 自 2.4.0 版本可用 </blockquote> 将磁盘上的文件转换为可读流 <div class="ts-block"> ```dts function createReadableStream(file: string): ReadableStream; ``` </div> ## getRequest <div class="ts-block"> ```dts function getRequest({ request, base, bodySizeLimit }: { request: import('http').IncomingMessage; base: string; bodySizeLimit?: number; }): Promise<Request>; ``` </div> ## setResponse <div class="ts-block"> ```dts function setResponse( res: import('http').ServerResponse, response: Response ): Promise<void>; ``` </div> # @sveltejs/kit/vite ```js // @noErrors import { sveltekit } from '@sveltejs/kit/vite'; ``` ## sveltekit 返回 SvelteKit Vite 插件。 <div class="ts-block"> ```dts function sveltekit(): Promise<import('vite').Plugin[]>; ``` </div> # $app/environment ```js // @noErrors import { browser, building, dev, version } from '$app/environment'; ``` ## browser 如果应用程序在浏览器中运行，则为 `true`。 <div class="ts-block"> ```dts const browser: boolean; ``` </div> ## building SvelteKit 在 `build` 步骤中通过运行来分析您的应用程序。在此过程中，`building` 为 `true`。这也适用于预渲染过程。 <div class="ts-block"> ```dts const building: boolean; ``` </div> ## dev 表示开发服务端是否正在运行。这不能保证与 `NODE_ENV` 或 `MODE` 对应。 <div class="ts-block"> ```dts const dev: boolean; ``` </div> ## version `config.kit.version.name` 的值。 <div class="ts-block"> ```dts const version: string; ``` </div> # $app/forms ```js // @noErrors import { applyAction, deserialize, enhance } from '$app/forms'; ``` ## applyAction 此 action 使用给定数据更新当前页面的 `form` 属性并更新 `page.status`。如果出现错误，它会重定向到最近的错误页面。 <div class="ts-block"> ```dts function applyAction< Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined >( result: import('@sveltejs/kit').ActionResult< Success, Failure > ): Promise<void>; ``` </div> ## deserialize 使用此函数来反序列化表单提交的响应。用法： ```js // @errors: 7031 import { deserialize } from '$app/forms'; async function handleSubmit(event) { const response = await fetch('/form?/action', { method: 'POST', body: new FormData(event.target) }); const result = deserialize(await response.text()); // ... } ``` <div class="ts-block"> ```dts function deserialize< Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined >( result: string ): import('@sveltejs/kit').ActionResult<Success, Failure>; ``` </div> ## enhance 此 action 增强了一个原本无需 JavaScript 就能工作的 `<form>` 元素。 `submit` 函数在提交时会被调用，传入给定的 FormData 和应该触发的 `action`。如果调用 `cancel`，表单将不会被提交。 您可以使用 abort `controller` 在另一个提交开始时取消当前提交。 如果返回一个函数，则该函数将被调用，并传入来自服务端的响应。如果没有返回任何内容，将使用后备处理。 如果未设置此函数或其返回值，它将： - 如果 action 与表单在相同的页面上，则回退到使用返回的数据更新 `form` prop - 更新 `page.status` - 重置 `<form>` 元素并在成功提交且没有重定向响应的情况下使所有数据失效。 - 在有重定向响应的情况下进行重定向 - 在出现意外错误时重定向到最近的错误页面 如果您提供了带有回调的自定义函数并想使用默认行为，请在回调中调用 `update`。 <div class="ts-block"> ```dts function enhance< Success extends Record<string, unknown> | undefined, Failure extends Record<string, unknown> | undefined >( form_element: HTMLFormElement, submit?: import('@sveltejs/kit').SubmitFunction< Success, Failure > ): { destroy(): void; }; ``` </div> # $app/navigation ```js // @noErrors import { afterNavigate, beforeNavigate, disableScrollHandling, goto, invalidate, invalidateAll, onNavigate, preloadCode, preloadData, pushState, replaceState } from '$app/navigation'; ``` ## afterNavigate 一个生命周期函数，在当前组件挂载时以及每当我们导航到新的 URL 时，运行提供的 `callback`。 `afterNavigate` 必须在组件初始化期间调用。只要组件保持挂载状态，它就会一直处于活动状态。 <div class="ts-block"> ```dts function afterNavigate( callback: ( navigation: import('@sveltejs/kit').AfterNavigate ) => void ): void; ``` </div> ## beforeNavigate 一个导航拦截器，在我们导航到一个 URL 之前触发，无论是通过点击链接、调用 `goto(...)`还是使用浏览器的前进/后退控件。 调用 `cancel()` 将阻止导航完成。如果 `navigation.type === 'leave'` — 意味着用户正在离开应用（或关闭标签页）— 调用 `cancel` 将触发原生浏览器的卸载确认对话框。在这种情况下，导航可能会被取消，也可能不会，取决于用户的响应。 当导航到不是 SvelteKit 拥有的路由时（因此由 SvelteKit 的客户端路由器控制），`navigation.to.route.id` 将为 `null`。 如果导航将（如果不取消）导致文档卸载 — 换句话说，'leave' 导航和 `navigation.to.route === null` 的 'link' 导航 — `navigation.willUnload` 为 `true`。 `beforeNavigate` 必须在组件初始化期间调用。只要组件保持挂载状态，它就会一直处于活动状态。 <div class="ts-block"> ```dts function beforeNavigate( callback: ( navigation: import('@sveltejs/kit').BeforeNavigate ) => void ): void; ``` </div> ## disableScrollHandling 如果在导航后页面更新时调用（例如在 `onMount` 或 `afterNavigate` 或 action 中），这将禁用 SvelteKit 的内置滚动处理。 这通常不建议使用，因为它会破坏用户的预期行为。 <div class="ts-block"> ```dts function disableScrollHandling(): void; ``` </div> ## goto 允许您以编程方式导航到给定的路由，并提供诸如保持当前元素焦点等选项。 返回一个 Promise，当 SvelteKit 导航（或导航失败，在这种情况下 promise 会 reject）到指定的 `url` 时 resolve。 对于外部 URL，请使用 `window.location = url` 而不是调用 `goto(url)`。 <div class="ts-block"> ```dts function goto( url: string | URL, opts?: | { replaceState?: boolean | undefined; noScroll?: boolean | undefined; keepFocus?: boolean | undefined; invalidateAll?: boolean | undefined; state?: App.PageState | undefined; } | undefined ): Promise<void>; ``` </div> ## invalidate 如果当前活动页面的任何 `load` 函数通过 `fetch` 或 `depends` 依赖于相关的 `url`，则会导致这些函数重新运行。返回一个 Promise，在页面随后更新时 resolve。 如果参数以 `string` 或 `URL` 形式给出，它必须解析为传递给 `fetch` 或 `depends` 的相同 URL（包括查询参数）。 要创建自定义标识符，请使用以 `[a-z]+:` 开头的字符串（例如 `custom:state`）— 这是一个有效的 URL。 `function` 参数可用于定义自定义谓词。它接收完整的 `URL` 并在返回 `true` 时导致 `load` 重新运行。 如果您想基于模式而不是精确匹配来使无效化，这很有用。 ```ts // 示例：匹配 '/path'，不考虑查询参数 import { invalidate } from '$app/navigation'; invalidate((url) => url.pathname === '/path'); ``` <div class="ts-block"> ```dts function invalidate( resource: string | URL | ((url: URL) => boolean) ): Promise<void>; ``` </div> ## invalidateAll 导致当前活动页面的所有 `load` 函数重新运行。返回一个 Promise，在页面随后更新时 resolve。 <div class="ts-block"> ```dts function invalidateAll(): Promise<void>; ``` </div> ## onNavigate 一个生命周期函数，在我们导航到新的 URL 之前立即运行提供的 `callback`，但在完整页面导航期间除外。 如果您返回一个 `Promise`，SvelteKit 将等待它 resolve 后才完成导航。这允许您 — 例如 — 使用 `document.startViewTransition`。避免使用解析较慢的 promise，因为导航会显得停滞不前。 如果从回调返回一个函数（或 resolve 为函数的 `Promise`），它将在 DOM 更新后被调用。 `onNavigate` 必须在组件初始化期间调用。只要组件保持挂载状态，它就会一直保持活动状态。 <div class="ts-block"> ```dts function onNavigate( callback: ( navigation: import('@sveltejs/kit').OnNavigate ) => MaybePromise<(() => void) | void> ): void; ``` </div> ## preloadCode 以编程方式导入尚未获取的路由的代码。通常，您可能会调用这个来加速后续导航。 您可以通过任何匹配的路径名指定路由，如 `/about`（匹配 `src/routes/about/+page.svelte`）或 `/blog/*`（匹配 `src/routes/blog/[slug]/+page.svelte`）。 与 `preloadData` 不同，这不会调用 `load` 函数。返回一个 Promise，在模块导入完成时 resolves。 <div class="ts-block"> ```dts function preloadCode(pathname: string): Promise<void>; ``` </div> ## preloadData 以编程方式预加载给定页面，这意味着 1. 确保页面的代码已加载，并且 2. 调用页面 load 函数并传入适当的选项。 这与 SvelteKit 在用户点击或将鼠标悬停在带有 `data-sveltekit-preload-data` 的 `<a>` 元素上时触发的行为相同。 如果下一次导航是到 `href`，将使用从 load 返回的值，使导航变得即时。 返回一个 Promise，在预加载完成后，它将 resolve 为运行新路由的 `load` 函数的结果。 <div class="ts-block"> ```dts function preloadData(href: string): Promise< | { type: 'loaded'; status: number; data: Record<string, any>; } | { type: 'redirect'; location: string; } >; ``` </div> ## pushState 以编程方式使用给定的 `page.state` 创建新的历史条目。要使用当前 URL，您可以将 `''` 作为第一个参数传递。用于[浅层路由](/docs/kit/shallow-routing)。 <div class="ts-block"> ```dts function pushState( url: string | URL, state: App.PageState ): void; ``` </div> ## replaceState 以编程方式用给定的 `page.state` 替换当前历史条目。要使用当前 URL，您可以将 `''` 作为第一个参数传递。用于[浅层路由](/docs/kit/shallow-routing)。 <div class="ts-block"> ```dts function replaceState( url: string | URL, state: App.PageState ): void; ``` </div> # $app/paths ```js // @noErrors import { assets, base, resolveRoute } from '$app/paths'; ``` ## assets 一个匹配 [`config.kit.paths.assets`](/docs/kit/configuration#paths)的绝对路径。 > [!NOTE] 如果指定了 `config.kit.paths.assets` 的值，它将在 `vite dev` 或 `vite preview` 期间被替换为 `'/_svelte_kit_assets'`，因为资源还没有位于它们最终的 URL 上。 <div class="ts-block"> ```dts let assets: | '' | `https://${string}` | `http://${string}` | '/_svelte_kit_assets'; ``` </div> ## base 一个匹配 [`config.kit.paths.base`](/docs/kit/configuration#paths) 的字符串。 使用示例：`<a href="{base}/your-page">链接</a>` <div class="ts-block"> ```dts let base: '' | `/${string}`; ``` </div> ## resolveRoute 使用参数填充路由 ID 以解析路径名。 ```js // @errors: 7031 import { resolveRoute } from '$app/paths'; resolveRoute(`/blog/[slug]/[...somethingElse]`, { slug: 'hello-world', somethingElse: 'something/else' }); // `/blog/hello-world/something/else` ``` <div class="ts-block"> ```dts function resolveRoute( id: string, params: Record<string, string | undefined> ): string; ``` </div> # $app/server ```js // @noErrors import { read } from '$app/server'; ``` ## read <blockquote class="since note"> 从 2.4.0 版本开始可用 </blockquote> 从文件系统中读取导入资源的内容 ```js // @errors: 7031 import { read } from '$app/server'; import somefile from './somefile.txt'; const asset = read(somefile); const text = await asset.text(); ``` <div class="ts-block"> ```dts function read(asset: string): Response; ``` </div> # $app/state SvelteKit 通过 `$app/state` 模块提供了三个只读状态对象 — `page`、`navigating` 和 `updated`。 > [!NOTE] > 此模块在 2.12 版本中添加。如果您使用的是早期版本的 SvelteKit，请使用 [`$app/stores`]($app-stores)。 ```js // @noErrors import { navigating, page, updated } from '$app/state'; ``` ## navigating 一个表示正在进行的导航的只读对象，具有 `from`、`to`、`type` 和（如果 `type === 'popstate'`）`delta` 属性。 当没有导航发生时或在服务端渲染期间，这些值为 `null`。 <div class="ts-block"> ```dts const navigating: | import('@sveltejs/kit').Navigation | { from: null; to: null; type: null; willUnload: null; delta: null; complete: null; }; ``` </div> ## page 一个包含当前页面信息的响应式对象，用于以下几个用途： - 在组件树的任何位置检索所有页面/布局的组合 `data`（另见 [加载数据](/docs/kit/load)） - 在组件树的任何位置检索 `form` prop 的当前值（另见 [表单 actions](/docs/kit/form-actions)） - 检索通过 `goto`、`pushState` 或 `replaceState` 设置的页面状态（另见 [goto](/docs/kit/$app-navigation#goto) 和 [浅路由](/docs/kit/shallow-routing)） - 检索元数据，如当前 URL、当前路由及其参数，以及是否发生错误 ```svelte <!--- file: +layout.svelte ---> <script> import { page } from '$app/state'; </script> <p>当前位置 {page.url.pathname}</p> {#if page.error} <span class="red">检测到问题</span> {:else} <span class="small">所有系统正常运行</span> {/if} ``` 在服务端，值只能在渲染期间读取（换句话说，不能在如 `load` 函数等中读取）。在浏览器中，可以随时读取这些值。 <div class="ts-block"> ```dts const page: import('@sveltejs/kit').Page; ``` </div> ## updated 一个初始值为 `false` 的响应式只读值。如果 [`version.pollInterval`](/docs/kit/configuration#version) 设置为非零值，SvelteKit 将轮询检查应用程序的新版本，当检测到新版本时，将 `current` 更新为 `true`。无论是否轮询，`updated.check()` 都将强制立即检查。 <div class="ts-block"> ```dts const updated: { get current(): boolean; check(): Promise<boolean>; }; ``` </div> # $app/stores 此模块包含从 [`$app/state`]($app-state) 导出的基于 store 的等价物。如果您使用的是 SvelteKit 2.12 或更高版本，请使用该模块代替。 ```js // @noErrors import { getStores, navigating, page, updated } from '$app/stores'; ``` ## getStores <div class="ts-block"> ```dts function getStores(): { page: typeof page; navigating: typeof navigating; updated: typeof updated; }; ``` </div> ## 导航 <blockquote class="tag deprecated note"> 请改用 `$app/state` 中的 `navigating`（需要 Svelte 5，[查看更多信息](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)） </blockquote> 一个可读 store。当导航开始时，其值为一个具有 `from`、`to`、`type` 和（如果 `type === 'popstate'`）`delta` 属性的 `Navigation` 对象。当导航结束时，其值恢复为 `null`。 在服务端上，此 store 只能在组件初始化期间被订阅。在浏览器中，它可以在任何时候被订阅。 <div class="ts-block"> ```dts const navigating: import('svelte/store').Readable< import('@sveltejs/kit').Navigation | null >; ``` </div> ## page <blockquote class="tag deprecated note"> 请改用 `$app/state` 中的 `page`（需要 Svelte 5，[查看更多信息](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)） </blockquote> 一个可读 store ，其值包含页面数据。 在服务端上，此 store 只能在组件初始化期间被订阅。在浏览器中，它可以在任何时候被订阅。 <div class="ts-block"> ```dts const page: import('svelte/store').Readable< import('@sveltejs/kit').Page >; ``` </div> ## updated <blockquote class="tag deprecated note"> 请改用 `$app/state` 中的 `updated`（需要 Svelte 5，[查看更多信息](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)） </blockquote> 一个可读 store ，其初始值为 `false`。如果 [`version.pollInterval`](/docs/kit/configuration#version) 为非零值，SvelteKit 将轮询应用程序的新版本，并在检测到新版本时将 store 值更新为 `true`。无论是否轮询，`updated.check()` 都将强制立即检查。 在服务端上，此 store 只能在组件初始化期间被订阅。在浏览器中，它可以在任何时候被订阅。 <div class="ts-block"> ```dts const updated: import('svelte/store').Readable<boolean> & { check(): Promise<boolean>; }; ``` </div> # $env/dynamic/private 此模块提供对运行时环境变量的访问，这些变量由您运行的平台定义。例如，如果您使用 [`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node)（或运行 [`vite preview`](/docs/kit/cli)），这相当于 `process.env`。此模块只包含*不*以 [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) 开头且*确实*以 [`config.kit.env.privatePrefix`](/docs/kit/configuration#env)（如果配置了）开头的变量。 此模块不能导入到客户端代码中。 动态环境变量不能在预渲染期间使用。 ```ts import { env } from '$env/dynamic/private'; console.log(env.DEPLOYMENT_SPECIFIC_VARIABLE); ``` > 在 `dev` 环境中，`$env/dynamic` 始终包含来自 `.env` 的环境变量。在 `prod` 环境中，这种行为将取决于您使用的适配器。 # $env/dynamic/public 类似于 [`$env/dynamic/private`](/docs/kit/$env-dynamic-private) ，但只包含以 [`config.kit.env.publicPrefix`](/docs/kit/configuration#env)（默认为 `PUBLIC_`）开头的变量，因此可以安全地暴露给客户端代码。 请注意，所有公共动态环境变量都必须从服务端发送到客户端，这会导致更大的网络请求 — 如果可能的话，请使用 `$env/static/public` 代替。 动态环境变量不能在预渲染期间使用。 ```ts import { env } from '$env/dynamic/public'; console.log(env.PUBLIC_DEPLOYMENT_SPECIFIC_VARIABLE); ``` # $env/static/private 由 Vite 从 `.env` 文件和 `process.env` [加载的环境变量](https://vitejs.dev/guide/env-and-mode.html#env-files)。与 [`$env/dynamic/private`](/docs/kit/$env-dynamic-private) 类似，此模块不能导入到客户端代码中。此模块仅包含*不*以 [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) 开头，且*确实*以 [`config.kit.env.privatePrefix`](/docs/kit/configuration#env) 开头的变量（如果已配置）。 _与_ [`$env/dynamic/private`](/docs/kit/$env-dynamic-private) _不同_，从此模块导出的值在构建时被静态注入到您的代码包中，这使得可以进行死代码消除等优化。 ```ts import { API_KEY } from '$env/static/private'; ``` 请注意，您的代码中引用的所有环境变量都应该被声明（例如在 `.env` 文件中），即使它们在应用程序部署时才有值： ``` MY_FEATURE_FLAG="" ``` 您可以通过命令行覆盖 `.env` 的值，如下所示： ```bash MY_FEATURE_FLAG="enabled" npm run dev ``` # $env/static/public 类似于 [`$env/static/private`](/docs/kit/$env-static-private)，但它只包含以 [`config.kit.env.publicPrefix`](/docs/kit/configuration#env)（默认为 `PUBLIC_`）开头的环境变量，因此可以安全地暴露给客户端代码。 这些值在构建时会被静态替换。 ```ts import { PUBLIC_BASE_URL } from '$env/static/public'; ``` # $lib SvelteKit 自动使用 `$lib` 导入别名，使 `src/lib` 下的文件可用。您可以在您的[配置文件](configuration#files)中更改此别名指向的目录。 ```svelte <!--- file: src/lib/Component.svelte ---> 一个可重用的组件 ``` ```svelte <!--- file: src/routes/+page.svelte ---> <script> import Component from '$lib/Component.svelte'; </script> <Component /> ``` # $service-worker ```js // @noErrors import { base, build, files, prerendered, version } from '$service-worker'; ``` 此模块仅在 [service workers](/docs/kit/service-workers) 中可用。 ## base 部署的 `base` 路径。通常这等同于 `config.kit.paths.base`，但它是从 `location.pathname` 计算得出的，这意味着即使网站部署到子目录中，它也能正常工作。 注意这里有 `base` 但没有 `assets`，因为当指定了 `config.kit.paths.assets` 时不能使用 service workers。 <div class="ts-block"> ```dts const base: string; ``` </div> ## build 一个由 Vite 生成的文件的 URL 字符串数组，适合用 `cache.addAll(build)` 进行缓存。在开发过程中，这是一个空数组。 <div class="ts-block"> ```dts const build: string[]; ``` </div> ## files 一个由静态目录（或由 `config.kit.files.assets` 指定的任何目录）中的文件的 URL 字符串数组。您可以使用 [`config.kit.serviceWorker.files`](/docs/kit/configuration) 自定义 `static` 目录包含的文件。 <div class="ts-block"> ```dts const files: string[]; ``` </div> ## prerendered 一个对应于预渲染页面和端点的路径名数组。在开发过程中，这是一个空数组。 <div class="ts-block"> ```dts const prerendered: string[]; ``` </div> ## version 参见[`config.kit.version`](/docs/kit/configuration#version)。它在 service workers 内生成唯一的缓存名称时很有用，这样您的应用程序的后续部署可以使旧的缓存失效。 <div class="ts-block"> ```dts const version: string; ``` </div> # 配置 您的项目配置位于项目根目录下的 `svelte.config.js` 文件中。除了 SvelteKit 外，此配置对象还被其他与 Svelte 集成的工具（如编辑器扩展）使用。 ```js /// 文件: svelte.config.js // @文件名: ambient.d.ts declare module '@sveltejs/adapter-auto' { const plugin: () => import('@sveltejs/kit').Adapter; export default plugin; } // @文件名: index.js // ---切割--- import adapter from '@sveltejs/adapter-auto'; /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { adapter: adapter() } }; export default config; ``` ## 配置 <div class="ts-block"> ```dts interface Config {/*…*/} ``` <div class="ts-block-property"> ```dts compilerOptions?: CompileOptions; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `{}` </div> 传递给 [`svelte.compile`](/docs/svelte/svelte-compiler#CompileOptions) 的选项。 </div> </div> <div class="ts-block-property"> ```dts extensions?: string[]; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `[".svelte"]` </div> 应视为 Svelte 文件的文件扩展名列表。 </div> </div> <div class="ts-block-property"> ```dts kit?: KitConfig; ``` <div class="ts-block-property-details"> SvelteKit 配置选项 </div> </div> <div class="ts-block-property"> ```dts preprocess?: any; ``` <div class="ts-block-property-details"> 预处理选项（如果有）。预处理也可以通过 Vite 的预处理功能实现。 </div> </div> <div class="ts-block-property"> ```dts vitePlugin?: PluginOptions; ``` <div class="ts-block-property-details"> `vite-plugin-svelte` 插件选项。 </div> </div> <div class="ts-block-property"> ```dts [key: string]: any; ``` <div class="ts-block-property-details"> 任何需要 Svelte 集成工具的额外选项。 </div> </div></div> ## KitConfig `kit` 属性用于配置 SvelteKit，并可以具有以下属性： ## adapter <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `undefined` </div> 当执行 `vite build` 时运行您的 [适配器](/docs/kit/adapters)。它决定如何将输出转换为适应不同平台的格式。 <div class="ts-block-property-children"> </div> ## alias <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `{}` </div> 一个包含零个或多个别名的对象，用于替换 `import` 语句中的值。这些别名会自动传递给 Vite 和 TypeScript。 ```js // @errors: 7031 /// 文件: svelte.config.js /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { 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` 中所需的别名配置。 <div class="ts-block-property-children"> </div> ## appDir <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `"_app"` </div> SvelteKit 存放其内容的目录，包括静态资源（如 JS 和 CSS）及内部使用的路由。 如果指定了 `paths.assets`，将有两个应用程序目录 —— `${paths.assets}/${appDir}` 和 `${paths.base}/${appDir}`。 <div class="ts-block-property-children"> </div> ## csp <div class="ts-block-property-bullets"> </div> [内容安全策略 (Content Security Policy)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) 配置。CSP 有助于保护您的用户免受跨站脚本 (XSS) 攻击，通过限制资源加载来源。例如，类似这样的配置…… ```js // @errors: 7031 /// 文件: svelte.config.js /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { csp: { directives: { 'script-src': ['self'] }, // 必须指定 `report-uri` 或 `report-to` 指令，或同时指定二者 reportOnly: { 'script-src': ['self'], 'report-uri': ['/'] } } } }; export default 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 转场](/tutorial/svelte/transition) 的工作方式是创建一个内联 `<style>` 元素。如果您在应用中使用这些功能，必须要么不指定 `style-src` 指令，要么添加 `unsafe-inline`。 如果需要更动态的配置，可以使用 [`handle` hook](/docs/kit/hooks#Server-hooks-handle) 自行构建 CSP。 <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors mode?: 'hash' | 'nonce' | 'auto'; ``` <div class="ts-block-property-details"> 指定是否使用哈希或 nonce 来限制 `<script>` 和 `<style>` 元素。`'auto'` 会在预渲染页面中使用哈希，而在动态渲染页面中使用 nonce。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors directives?: CspDirectives; ``` <div class="ts-block-property-details"> 将添加到 `Content-Security-Policy` 标头的指令。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors reportOnly?: CspDirectives; ``` <div class="ts-block-property-details"> 将添加到 `Content-Security-Policy-Report-Only` 标头的指令。 </div> </div> </div> ## csrf <div class="ts-block-property-bullets"> </div> 防止 [跨站请求伪造（CSRF）](https://owasp.org/www-community/attacks/csrf) 的攻击。 <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors checkOrigin?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `true` </div> 是否在 `POST`、`PUT`、`PATCH` 或 `DELETE` 表单提交中检查传入的 `origin` 标头并验证是否与服务端的 origin 匹配。 要允许人们从其他来源向您的应用发送 `POST`、`PUT`、`PATCH` 或 `DELETE` 请求，其 `Content-Type` 为 `application/x-www-form-urlencoded`、`multipart/form-data` 或 `text/plain`，需要禁用此选项。请谨慎操作！ </div> </div> </div> ## 嵌入式应用 <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `false` </div> 应用是否嵌入在一个更大的应用中。如果设置为 `true`，SvelteKit 将在 `%sveltekit.body%` 的父级上而不是 `window` 上添加与导航相关的事件监听器，并从服务端传递 `params`，而不是从 `location.pathname` 推导。 请注意：通常不支持在同一页面中嵌入多个 SvelteKit 应用并在它们之间使用客户端 SvelteKit 功能（例如推送历史状态等操作假设只有一个实例）。 <div class="ts-block-property-children"> </div> ## 环境变量配置 (env) <div class="ts-block-property-bullets"> </div> 环境变量配置 <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors dir?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"."` </div> 用于搜索 `.env` 文件的目录。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors publicPrefix?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"PUBLIC_"` </div> 一个前缀，用于指示环境变量可以安全地暴露给客户端代码。参考 [`$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) 必须单独设置，但通常不需要使用该功能。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors privatePrefix?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `""` - <span class="tag since">自版本</span> v1.21.0 开始可用 </div> 一个前缀，用于指示环境变量不能暴露给客户端代码。不符合公共或私有前缀的环境变量将完全被丢弃。参考 [`$env/static/private`](/docs/kit/$env-static-private) 和 [`$env/dynamic/private`](/docs/kit/$env-dynamic-private)。 </div> </div> </div> ## 文件路径配置 (files) <div class="ts-block-property-bullets"> </div> 定义项目中各种文件的位置。 <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors assets?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"static"` </div> 一个用于存放静态文件的位置，这些文件应具有稳定的 URL 并且不进行任何处理，例如 `favicon.ico` 或 `manifest.json`。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors hooks?: {/*…*/} ``` <div class="ts-block-property-details"> <div class="ts-block-property-children"><div class="ts-block-property"> ```ts // @noErrors client?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/hooks.client"` </div> 客户端 [hooks](/docs/kit/hooks) 文件的位置。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors server?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/hooks.server"` </div> 服务端 [hooks](/docs/kit/hooks) 文件的位置。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors universal?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/hooks"` - <span class="tag since">自版本</span> v2.3.0 开始可用 </div> 通用 [hooks](/docs/kit/hooks) 文件的位置。 </div> </div></div> </div> </div> <div class="ts-block-property"> ```ts // @noErrors lib?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/lib"` </div> 应用的内部库位置，可在代码库中通过 `$lib` 访问。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors params?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/params"` </div> 包含 [参数匹配器](/docs/kit/advanced-routing#Matching) 的目录。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors routes?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/routes"` </div> 定义应用结构的文件位置 (参考 [Routing](/docs/kit/routing))。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors serviceWorker?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/service-worker"` </div> server workers 入口点的位置 (参考 [server workers ](/docs/kit/service-workers))。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors appTemplate?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/app.html"` </div> HTML 响应模板的位置。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors errorTemplate?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"src/error.html"` </div> 回退错误响应的模板位置。 </div> </div> </div> ## inlineStyleThreshold <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `0` </div> 将 CSS 内联到 HTML 头部的 `<style>` 块中。此选项是一个数字，指定 UTF-16 代码单元（由 [String.length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) 属性定义）中 CSS 文件的最大长度。页面需要的所有小于此值的 CSS 文件都会被合并并内联到 `<style>` 块中。 > [!NOTE] 这会减少初始请求并可以提高 [First Contentful Paint](https://web.dev/first-contentful-paint) 指标。但这会生成更大的 HTML 输出，并降低浏览器缓存的效果。请谨慎使用。 <div class="ts-block-property-children"> </div> ## moduleExtensions <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `[".js", ".ts"]` </div> 一个文件扩展名数组，SvelteKit 会将其视为模块。不匹配 `config.extensions` 或 `config.kit.moduleExtensions` 的扩展名文件将被路由器忽略。 <div class="ts-block-property-children"> </div> ## outDir <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `".svelte-kit"` </div> SvelteKit 在 `dev` 和 `build` 阶段将文件写入的目录。您应该将此目录排除在版本控制之外。 <div class="ts-block-property-children"> </div> ## output <div class="ts-block-property-bullets"> </div> 与构建输出格式相关的选项。 <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors preloadStrategy?: 'modulepreload' | 'preload-js' | 'preload-mjs'; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `"modulepreload"` - <span class="tag since">可用版本</span> v1.8.4 </div> 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` 被更广泛地支持。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors bundleStrategy?: 'split' | 'single' | 'inline'; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `'split'` - <span class="tag since">可用版本</span> v2.13.0 </div> - 如果选择 `'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) 来调整捆绑行为。 </div> </div> </div> ## paths <div class="ts-block-property-bullets"> </div> <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors assets?: '' | `http://${string}` | `https://${string}`; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `""` </div> 一个表示应用文件提供路径的绝对路径。这在您的文件从某种存储桶提供时很有用。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors base?: '' | `/${string}`; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `""` </div> 一个相对根路径，必须以 `/` 开头但不能以 `/` 结尾（例如 `/base-path`），除非它是空字符串。这指定了应用的服务路径，并允许应用运行在非根路径中。需要注意，您必须为所有的相对根链接添加 base 值前缀，否则它们将指向域的根路径，而非您的 `base`（浏览器的工作方式）。您可以使用 [`base` from `$app/paths`](/docs/kit/$app-paths#base) 来处理：`<a href="{base}/your-page">Link</a>`。如果您需要经常这样写，或许可以将其抽象成一个可重复使用的组件。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors relative?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认值</span> `true` - <span class="tag since">可用版本</span> v1.9.0 </div> 是否使用相对资源路径。 如果为 `true`，在服务端渲染时，`base` 和 `assets`（从 `$app/paths` 导入）会被替换为相对资源路径，生成更具可移植性的 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` 会按配置指定。 </div> </div> </div> ## 预渲染（prerender） <div class="ts-block-property-bullets"> </div> 详见 [预渲染](/docs/kit/page-options#prerender)。 <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors concurrency?: number; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `1` </div> 可以同时预渲染多少个页面。尽管 JavaScript 是单线程的，但如果预渲染性能受网络限制（例如从远程 CMS 加载内容），在等待网络响应时处理其他任务可以提高速度。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors crawl?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `true` </div> SvelteKit 是否通过从 `entries` 中的链接来查找预渲染的页面。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors entries?: Array<'*' | `/${string}`>; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `["*"]` </div> 一个包含待预渲染页面，或用于开始爬取的数组（如果 `crawl: true`）。字符串 `*` 包括所有不含必填 `[parameters]` 的路由，可选参数为空（因为 SvelteKit 无法知道参数的值应该是什么）。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors handleHttpError?: PrerenderHttpErrorHandlerValue; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `"fail"` - <span class="tag since">自</span> v1.15.7 可用 </div> 如何处理预渲染应用时遇到的 HTTP 错误。 - `'fail'` — 构建失败 - `'ignore'` - 安静地忽略错误并继续 - `'warn'` — 继续但打印警告 - `(details) => void` — 一个使用带有 `status`、`path`、`referrer`、`referenceType` 和 `message` 属性的 `details` 对象的自定义错误处理器。如果在该函数中 `throw`，构建将失败 ```js // @errors: 7031 /// file: svelte.config.js /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { prerender: { handleHttpError: ({ path, referrer, message }) => { // 忽略指向有设计感的404页面的链接 if (path === '/not-found' && referrer === '/blog/how-we-built-our-404-page') { return; } // 否则，构建失败 throw new Error(message); } } } }; ``` </div> </div> <div class="ts-block-property"> ```ts // @noErrors handleMissingId?: PrerenderMissingIdHandlerValue; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `"fail"` - <span class="tag since">自</span> v1.15.7 可用 </div> 当一个预渲染页面的哈希链接没有对应的目标页面中的 `id` 时，该如何响应。 - `'fail'` — 构建失败 - `'ignore'` - 安静地忽略错误并继续 - `'warn'` — 继续但打印警告 - `(details) => void` — 一个使用带有 `path`、`id`、`referrers` 和 `message` 属性的 `details` 对象的自定义错误处理器。如果在该函数中 `throw`，构建将失败 </div> </div> <div class="ts-block-property"> ```ts // @noErrors handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `"fail"` - <span class="tag since">自</span> v1.16.0 可用 </div> 当由 `entries` 导出的条目与生成它的路由不匹配时，该如何响应。 - `'fail'` — 构建失败 - `'ignore'` - 安静地忽略错误并继续 - `'warn'` — 继续但打印警告 - `(details) => void` — 一个使用带有 `generatedFromId`、`entry`、`matchedId` 和 `message` 属性的 `details` 对象的自定义错误处理器。如果在该函数中 `throw`，构建将失败 </div> </div> <div class="ts-block-property"> ```ts // @noErrors origin?: string; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `"http://sveltekit-prerender"` </div> 在预渲染时，`url.origin` 的值；如果它被包含在渲染的内容中，则很有用。 </div> </div> </div> ## 路由器（router） <div class="ts-block-property-bullets"> </div> <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors type?: 'pathname' | 'hash'; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `"pathname"` - <span class="tag since">自</span> v2.14.0 可用 </div> 使用哪种类型的客户端路由器。 - `'pathname'` 是默认选项，意味着当前 URL 的路径名决定了路由。 - `'hash'` 表示路由由 `location.hash` 确定。在这种情况下，SSR 和预渲染被禁用。仅当 `pathname` 无法作为选项时推荐使用，例如由于您无法控制应用程序部署的 Web 服务端。 这种方式有一些注意事项：您无法使用服务端渲染（或任何服务端逻辑），并且需要确保应用程序中的链接都以 /#/ 开头，否则它们将无法工作。除此之外，其他功能与普通 SvelteKit 应用程序完全相同。 </div> </div> </div> ## 服务工作器（serviceWorker） <div class="ts-block-property-bullets"> </div> <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors register?: boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `true` </div> 是否自动注册服务工作器（如果有）。 </div> </div> <div class="ts-block-property"> ```ts // @noErrors files?(filepath: string): boolean; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `(filename) => !/\.DS_Store/.test(filename)` </div> 决定您的 `static` 目录中的哪些文件可以在 `$service-worker.files` 中使用。 </div> </div> </div> ## TypeScript <div class="ts-block-property-bullets"> </div> <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors config?: (config: Record<string, any>) => Record<string, any> | void; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `(config) => config` - <span class="tag since">自</span> v1.3.0 可用 </div> 一个允许您编辑生成的 `tsconfig.json` 的函数。您可以直接修改配置（推荐）或返回一个新的配置。 这在扩展单一工作区根目录中的共享 `tsconfig.json` 时很有用。 </div> </div> </div> ## 版本（version） <div class="ts-block-property-bullets"> </div> 如果您在应用程序使用过程中部署新版本，客户端导航可能会有问题。如果新页面的代码已经加载，它可能包含过期内容；如果没有加载，应用程序的路由清单可能指向一个不再存在的 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`。 <div class="ts-block-property-children"> <div class="ts-block-property"> ```ts // @noErrors name?: string; ``` <div class="ts-block-property-details"> 当前应用程序版本字符串。如果指定，必须是确定性的（例如提交引用，而不是 `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() } } }; ``` </div> </div> <div class="ts-block-property"> ```ts // @noErrors pollInterval?: number; ``` <div class="ts-block-property-details"> <div class="ts-block-property-bullets"> - <span class="tag">默认</span> `0` </div> 轮询版本变化的时间间隔（单位：毫秒）。如果设置为 `0`，则不会进行轮询。 </div> </div> </div> # 命令行界面 SvelteKit 项目使用 [Vite](https://vitejs.dev)，这意味着您将主要使用其 CLI（通过 `npm run dev/build/preview` 脚本）： - `vite dev` — 启动开发服务端 - `vite build` — 构建应用程序的生产版本 - `vite preview` — 在本地运行生产版本 但是 SvelteKit 包含自己的命令行界面，用于初始化您的项目： ## svelte-kit sync `svelte-kit sync` 为您的项目创建 `tsconfig.json` 和所有生成的类型（您可以在路由文件中以 `./$types` 的形式导入）。当您创建一个新项目时，它会被列为 `prepare` 脚本，并且会作为 npm 生命周期的一部分自动运行，所以您通常不需要手动运行这个命令。 # 类型 ## 生成的类型 `RequestHandler` 和 `Load` 类型都接受一个 `Params` 参数，允许您为 `params` 对象定义类型。例如，这个端点需要 `foo`、`bar` 和 `baz` 参数： ```js /// file: src/routes/[foo]/[bar]/[baz]/+page.server.js // @errors: 2355 2322 1360 /** @type {import('@sveltejs/kit').RequestHandler<{ foo: string; bar: string; baz: string }>} */ export async function GET({ params }) { // ... } ``` 显然，这样编写很麻烦，而且不够灵活（如果您将 `[foo]` 目录重命名为 `[qux]`，类型将不再反映实际情况）。 为了解决这个问题，SvelteKit 为您的每个端点和页面生成 `.d.ts` 文件： ```ts /// file: .svelte-kit/types/src/routes/[foo]/[bar]/[baz]/$types.d.ts /// link: true import type * as Kit from '@sveltejs/kit'; type RouteParams = { foo: string; bar: string; baz: string; }; export type PageServerLoad = Kit.ServerLoad<RouteParams>; export type PageLoad = Kit.Load<RouteParams>; ``` 这些文件可以作为同级文件导入到您的端点和页面中，这要归功于 TypeScript 配置中的 [`rootDirs`](https://www.typescriptlang.org/tsconfig#rootDirs) 选项： ```js /// file: src/routes/[foo]/[bar]/[baz]/+page.server.js // @filename: $types.d.ts import type * as Kit from '@sveltejs/kit'; type RouteParams = { foo: string; bar: string; baz: string; } export type PageServerLoad = Kit.ServerLoad<RouteParams>; // @filename: index.js // @errors: 2355 // ---cut--- /** @type {import('./$types').PageServerLoad} */ export async function GET({ params }) { // ... } ``` ```js /// file: src/routes/[foo]/[bar]/[baz]/+page.js // @filename: $types.d.ts import type * as Kit from '@sveltejs/kit'; type RouteParams = { foo: string; bar: string; baz: string; } export type PageLoad = Kit.Load<RouteParams>; // @filename: index.js // @errors: 2355 // ---cut--- /** @type {import('./$types').PageLoad} */ export async function load({ params, fetch }) { // ... } ``` > [!NOTE] 要使此功能生效，您的 `tsconfig.json` 或 `jsconfig.json` 应该继承自生成的 `.svelte-kit/tsconfig.json`（其中 `.svelte-kit` 是您的 [`outDir`](configuration#outDir)）： > > `{ "extends": "./.svelte-kit/tsconfig.json" }` ### 默认 tsconfig.json 生成的 `.svelte-kit/tsconfig.json` 文件包含多种选项。有些是根据您的项目配置以编程方式生成的，一般情况下不应该在没有充分理由的情况下覆盖： ```json /// file: .svelte-kit/tsconfig.json { "compilerOptions": { "baseUrl": "..", "paths": { "$lib": "src/lib", "$lib/*": "src/lib/*" }, "rootDirs": ["..", "./types"] }, "include": ["../src/**/*.js", "../src/**/*.ts", "../src/**/*.svelte"], "exclude": ["../node_modules/**", "./**"] } ``` 其他一些选项是 SvelteKit 正常工作所必需的，除非您知道自己在做什么，否则也不应该修改： ```json /// file: .svelte-kit/tsconfig.json { "compilerOptions": { // 这确保类型使用 `import type` 显式导入， // 这是必需的，因为 svelte-preprocess // 否则无法正确编译组件 "importsNotUsedAsValues": "error", // Vite 一次编译一个 TypeScript 模块， // 而不是编译整个模块图 "isolatedModules": true, // TypeScript 无法'看到'您在标记中 // 何时使用导入的值，所以我们需要这个 "preserveValueImports": true, // 这确保 `vite build` 和 // `svelte-package` 都能正常工作 "lib": ["esnext", "DOM", "DOM.Iterable"], "moduleResolution": "node", "module": "esnext", "target": "esnext" } } ``` ## $lib 这是一个指向 `src/lib` 的简单别名，或者指向在 [`config.kit.files.lib`](configuration#files) 中指定的任何目录。它允许您访问常用组件和实用工具模块，而无需使用 `../../../../` 这样的路径。 ### $lib/server `$lib` 的子目录。SvelteKit 会阻止您在客户端代码中导入 `$lib/server` 中的任何模块。参见[仅服务端模块](server-only-modules)。 ## app.d.ts `app.d.ts` 文件包含您的应用程序的环境类型，即无需显式导入就可以使用的类型。 这个文件中总是包含 `App` 命名空间。此命名空间包含几个影响您与某些 SvelteKit 功能交互的类型。 ## Error 定义预期和非预期错误的通用形状。预期错误使用 `error` 函数抛出。非预期错误由 `handleError` 钩子处理，这些钩子应该返回这种形状。 <div class="ts-block"> ```dts interface Error {/*…*/} ``` <div class="ts-block-property"> ```dts message: string; ``` <div class="ts-block-property-details"></div> </div></div> ## Locals 定义 `event.locals` 的接口，可以在服务端[hooks](/docs/kit/hooks)（`handle` 和 `handleError`）、仅服务端的 `load` 函数和 `+server.js` 文件中访问。 <div class="ts-block"> ```dts interface Locals {} ``` </div> ## PageData 定义 [page.data state](/docs/kit/$app-state#page) 和 [$page.data store](/docs/kit/$app-stores#page) 的通用形状 - 即所有页面之间共享的数据。 `./$types` 中的 `Load` 和 `ServerLoad` 函数将相应地被收窄。 对于仅存在于特定页面上的数据，请使用可选属性。不要添加索引签名（`[key: string]: any`）。 <div class="ts-block"> ```dts interface PageData {} ``` </div> ## PageState 定义 `page.state` 对象的形状，可以使用 `$app/navigation` 中的 [`pushState`](/docs/kit/$app-navigation#pushState) 和 [`replaceState`](/docs/kit/$app-navigation#replaceState) 函数来操作。 <div class="ts-block"> ```dts interface PageState {} ``` </div> ## Platform 如果您的适配器通过 `event.platform` 提供[平台特定上下文](/docs/kit/adapters#Platform-specific-context)，您可以在这里指定它。 <div class="ts-block"> ```dts interface Platform {} ``` </div>