SvelteKit 最新中文文档教程（1）—— 入门指南
<h2 id="前言">前言</h2><p>Svelte，一个语法简洁、入门容易，面向未来的前端框架。</p>
<p>从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，<strong>从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1</strong>：</p>
<p><img src="https://yayujs-blog.oss-cn-beijing.aliyuncs.com/405488775-48df16b1-939c-489b-8d52-6071869893f0.png"></p>
<p>Svelte 以其独特的编译时优化机制著称，具有<strong>轻量级</strong>、<strong>高性能</strong>、<strong>易上手</strong>等特性，<strong>非常适合构建轻量级 Web 项目</strong>。</p>
<p>为了帮助大家学习 Svelte，我同时搭建了 Svelte 最新的中文文档站点。</p>
<p>如果需要进阶学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！</p>
<p>欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。</p>
<h2 id="介绍">介绍</h2>
<h3 id="开始之前">开始之前</h3>
<blockquote>
<p>[!NOTE] 如果您是 Svelte 或 SvelteKit 的新手，我们建议查看交互式教程。</p>
<p>如果遇到问题，可以在 Discord 聊天室寻求帮助。</p>
</blockquote>
<h3 id="什么是-sveltekit">什么是 SvelteKit？</h3>
<p>SvelteKit 是一个使用 Svelte 快速开发稳健、高性能 Web 应用程序的框架。如果您来自 React，SvelteKit 类似于 Next。如果您来自 Vue，SvelteKit 类似于 Nuxt。</p>
<p>要了解更多关于可以用 SvelteKit 构建的应用程序类型，请参阅常见问题。</p>
<h3 id="什么是-svelte">什么是 Svelte？</h3>
<p>简而言之，Svelte 是一种编写用户界面组件的方式 —— 比如导航栏、评论区或联系表单 —— 这些组件用户可以在浏览器中看到并与之交互。Svelte 编译器将您的组件转换为可以运行的 JavaScript 来渲染页面的 HTML，以及为页面添加样式 CSS。您不需要了解 Svelte 就能理解本指南的其余部分，但了解它会有所帮助。如果您想了解更多，请查看 Svelte 教程。</p>
<h3 id="sveltekit-与-svelte-的区别">SvelteKit 与 Svelte 的区别</h3>
<p>Svelte 负责渲染 UI 组件。您可以组合这些组件并仅使用 Svelte 渲染整个页面，但要构建完整的应用程序，您需要的不仅仅是 Svelte。</p>
<p>SvelteKit 帮助您在遵循现代最佳实践的同时构建 Web 应用，并为常见的开发挑战提供解决方案。它提供从基本功能 —— 比如在点击链接时更新 UI 的路由器 —— 到更高级的功能。</p>
<p>它的广泛功能列表包括：仅加载最小所需代码的构建优化；离线支持；用户导航前的页面预加载；通过 SSR、浏览器客户端渲染或构建时预渲染来处理应用程序不同部分的可配置渲染；图像优化；等等。使用所有现代最佳实践构建应用程序非常复杂，但 SvelteKit 为您处理了所有繁琐的工作，这样您就可以专注于创造性的部分。</p>
<p>它利用带有 Svelte 插件的 Vite 来实现热模块替换 (HMR)，从而在浏览器中即时反映代码更改，提供闪电般快速且功能丰富的开发体验。</p>
<h2 id="创建项目">创建项目</h2>
<p>创建 SvelteKit 应用最简单的方法是运行 <code>npx sv create</code>：</p>
<pre><code class="language-bash">npx sv create my-app
cd my-app
npm install
npm run dev
</code></pre>
<p>第一个命令将在 <code>my-app</code> 目录中搭建一个新项目，并询问您是否要设置一些基本工具，比如 TypeScript。有关设置其他工具的指导，请参见集成。随后的命令将安装其依赖项并在 localhost:5173 上启动服务端。</p>
<p>这里有两个基本概念：</p>
<ul>
<li>应用的每个页面都是一个 Svelte 组件</li>
<li>通过在项目的 <code>src/routes</code> 目录中添加文件来创建页面。这些页面将被服务端渲染，以确保用户首次访问您的应用时速度尽可能快，之后客户端应用将接管</li>
</ul>
<p>尝试编辑文件以了解所有功能是如何工作的。</p>
<h3 id="编辑器设置">编辑器设置</h3>
<p>我们推荐使用 Visual Studio Code (简称 VS Code) 并安装 Svelte 扩展，但也支持许多其他编辑器。</p>
<h2 id="项目结构">项目结构</h2>
<p>一个典型的 SvelteKit 项目结构如下：</p>
<pre><code class="language-bash">my-project/
├ src/
│ ├ lib/
│ │ ├ server/
│ │ │ └ [您的仅服务端库文件]
│ │ └ [您的库文件]
│ ├ params/
│ │ └ [您的参数匹配器]
│ ├ routes/
│ │ └ [您的路由]
│ ├ app.html
│ ├ error.html
│ ├ hooks.client.js
│ ├ hooks.server.js
│ └ service-worker.js
├ static/
│ └ [您的静态资源]
├ tests/
│ └ [您的测试]
├ package.json
├ svelte.config.js
├ tsconfig.json
└ vite.config.js
</code></pre>
<p>您还会发现一些常见文件，如 <code>.gitignore</code> 和 <code>.npmrc</code>（如果您在运行 <code>npx sv create</code> 时选择了这些选项，还会有 <code>.prettierrc</code> 和 <code>eslint.config.js</code> 等）。</p>
<h3 id="项目文件">项目文件</h3>
<h4 id="src">src</h4>
<p><code>src</code> 目录包含了项目的主要内容。除了 <code>src/routes</code> 和 <code>src/app.html</code> 之外，其他都是可选的。</p>
<ul>
<li><code>lib</code> 包含您的库代码（实用工具和组件），可以通过 <code>$lib</code> 别名导入，或使用 <code>svelte-package</code> 打包分发
<ul>
<li><code>server</code> 包含您的仅服务端（server-only）库代码。可以使用 <code>$lib/server</code> 别名导入。SvelteKit 会阻止您在客户端代码中导入这些内容。</li>
</ul>
</li>
<li><code>params</code> 包含应用需要的任何参数匹配器</li>
<li><code>routes</code> 包含应用的路由。您也可以在这里放置仅在单个路由中使用的其他组件</li>
<li><code>app.html</code> 是您的页面模板 — 一个包含以下占位符的 HTML 文档：
<ul>
<li><code>%sveltekit.head%</code> — 应用需要的 <code><link></code> 和 <code><script></code> 元素，以及任何 <code><svelte:head></code> 内容</li>
<li><code>%sveltekit.body%</code> — 渲染页面的标记。这应该放在 <code><div></code> 或其他元素内，而不是直接放在 <code><body></code> 内，以防止浏览器插件注入元素后被水合过程销毁而导致的错误。如果不是这样情况，SvelteKit 会在开发时警告您</li>
<li><code>%sveltekit.assets%</code> — 如果指定了，则是 <code>paths.assets</code>，否则是到 <code>paths.base</code> 的相对路径</li>
<li><code>%sveltekit.nonce%</code> — 手动包含的链接和脚本的 CSP nonce（如果使用）</li>
<li><code>%sveltekit.env.%</code> - 这将在渲染时被替换为 <code></code> 环境变量，该变量必须以 <code>publicPrefix</code>（通常是 <code>PUBLIC_</code>）开头。如果没有匹配项，将回退到 <code>''</code></li>
</ul>
</li>
<li><code>error.html</code> 是在所有其他内容都失败时渲染的页面。它可以包含以下占位符：
<ul>
<li><code>%sveltekit.status%</code> — HTTP 状态码</li>
<li><code>%sveltekit.error.message%</code> — 错误信息</li>
</ul>
</li>
<li><code>hooks.client.js</code> 包含您的客户端钩子</li>
<li><code>hooks.server.js</code> 包含您的服务端钩子</li>
<li><code>service-worker.js</code> 包含您的 service worker</li>
</ul>
<p>（项目是包含 <code>.js</code> 还是 <code>.ts</code> 文件取决于您创建项目时是否选择使用 TypeScript。您可以使用本页底部的切换按钮在文档中的 JavaScript 和 TypeScript 之间切换。）</p>
<p>如果您在设置项目时添加了 Vitest，您的单元测试将位于 <code>src</code> 目录中，带有 <code>.test.js</code> 扩展名。</p>
<h4 id="static">static</h4>
<p>这里放置需要按原样提供的静态资源，如 <code>robots.txt</code> 或 <code>favicon.png</code>。</p>
<h4 id="tests">tests</h4>
<p>如果您在设置项目时添加了 Playwright 进行浏览器测试，测试文件将位于此目录中。</p>
<h4 id="packagejson">package.json</h4>
<p>您的 <code>package.json</code> 文件必须包含 <code>@sveltejs/kit</code>、<code>svelte</code> 和 <code>vite</code> 作为 <code>devDependencies</code>。</p>
<p>当您使用 <code>npx sv create</code> 创建项目时，您会注意到 <code>package.json</code> 包含了 <code>"type": "module"</code>。这意味着 <code>.js</code> 文件将被解释为带有 <code>import</code> 和 <code>export</code> 关键字的原生 JavaScript 模块。遗留的 CommonJS 文件需要一个 <code>.cjs</code> 文件扩展名。</p>
<h4 id="svelteconfigjs">svelte.config.js</h4>
<p>此文件包含您的 Svelte 和 SvelteKit 配置。</p>
<h4 id="tsconfigjson">tsconfig.json</h4>
<p>如果您在 <code>npx sv create</code> 期间添加了类型检查，此文件（或者如果您更喜欢对 <code>.js</code> 文件而不是 <code>.ts</code> 文件进行类型检查，则为 <code>jsconfig.json</code>）将配置 TypeScript。由于 SvelteKit 依赖于某些特定方式的配置设置，它会生成自己的 <code>.svelte-kit/tsconfig.json</code> 文件，您的配置将 <code>extends</code> 这个文件。</p>
<h4 id="viteconfigjs">vite.config.js</h4>
<p>SvelteKit 项目实际上就是一个使用 <code>@sveltejs/kit/vite</code> 插件的 Vite 项目，以及其他 Vite 配置。</p>
<h3 id="其他文件">其他文件</h3>
<h4 id="svelte-kit">.svelte-kit</h4>
<p>在开发和构建项目时，SvelteKit 将在 <code>.svelte-kit</code> 目录中生成文件（可通过 <code>outDir</code> 配置）。您可以忽略其内容，并随时删除它们（它们将在下次 <code>dev</code> 或 <code>build</code> 时重新生成）。</p>
<h2 id="web-标准">Web 标准</h2>
<p>在本文档中，您会看到对 SvelteKit 所基于的标准 Web APIs 的引用。我们没有重新发明轮子，而是<em>使用平台</em>，这意味着您现有的 Web 开发技能可以应用到 SvelteKit。反之，花时间学习 SvelteKit 也会帮助您在其他地方成为更好的 Web 开发者。</p>
<p>这些 API 在所有现代浏览器和许多非浏览器环境（如 Cloudflare Workers、Deno 和 Vercel Functions）中都可用。在开发过程中，以及在基于 Node 的环境（包括 AWS Lambda）的适配器中，必要时会通过 polyfills 提供这些 API（目前是这样 — Node 正在快速增加对更多 Web 标准的支持）。</p>
<p>特别是，您会熟悉以下内容：</p>
<h3 id="fetch-apis">Fetch APIs</h3>
<p>SvelteKit 使用 <code>fetch</code> 从网络获取数据。它在 hooks 和服务端路由以及浏览器中都可用。</p>
<blockquote>
<p>[!NOTE] 在 <code>load</code> 函数、服务端 hooks和 API 路由中提供了一个特殊版本的 <code>fetch</code>，用于在服务端渲染期间直接调用端点，而无需进行 HTTP 调用，同时保留凭证。（要在 <code>load</code> 之外的服务端代码中进行带凭证的请求，您必须显式传递 <code>cookie</code> 和/或 <code>authorization</code> 头部。）它还允许您进行相对地址请求，而服务端的 <code>fetch</code> 通常需要一个完整的 URL。</p>
</blockquote>
<p>除了 <code>fetch</code> 本身，Fetch API 还包括以下接口：</p>
<h4 id="request">Request</h4>
<p><code>Request</code> 的实例在 hooks 和服务端路由中可以通过 <code>event.request</code> 访问。它包含有用的方法，如 <code>request.json()</code> 和 <code>request.formData()</code>，用于获取发送到端点的数据。</p>
<h4 id="response">Response</h4>
<p><code>Response</code> 的实例由 <code>await fetch(...)</code> 和 <code>+server.js</code> 文件中的处理程序返回。从根本上说，SvelteKit 应用就是一个将 <code>Request</code> 转换为 <code>Response</code> 的机器。</p>
<h4 id="headers">Headers</h4>
<p><code>Headers</code> 接口允许您读取传入的 <code>request.headers</code> 和设置传出的 <code>response.headers</code>。例如，您可以如下获取 <code>request.headers</code>，并使用 <code>json</code> 便捷函数 发送修改后的 <code>response.headers</code>：</p>
<pre><code class="language-js">// @errors: 2461
/// file: src/routes/what-is-my-user-agent/+server.js
import { json } from '@sveltejs/kit';
/** @type {import('./$types').RequestHandler} */
export function GET({ request }) {
// 记录所有头部
console.log(...request.headers);
// 使用我们收到的头部创建 JSON Response
return json(
{
// 获取特定头部
userAgent: request.headers.get('user-agent')
},
{
// 在响应中设置头部
headers: { 'x-custom-header': 'potato' }
}
);
}
</code></pre>
<h3 id="formdata">FormData</h3>
<p>当处理 HTML 原生表单提交时，您将使用 <code>FormData</code> 对象。</p>
<pre><code class="language-js">// @errors: 2461
/// file: src/routes/hello/+server.js
import { json } from '@sveltejs/kit';
/** @type {import('./$types').RequestHandler} */
export async function POST(event) {
const body = await event.request.formData();
// 记录所有字段
console.log([...body]);
return json({
// 获取特定字段的值
name: body.get('name') ?? 'world'
});
}
</code></pre>
<h3 id="stream-apis">Stream APIs</h3>
<p>大多数情况下，您的端点会返回完整的数据，就像上面的 <code>userAgent</code> 示例那样。有时，您可能需要返回一个太大而无法一次性放入内存的响应，或者需要分块传递的响应，为此平台提供了流 — ReadableStream、WritableStream 和 TransformStream。</p>
<h3 id="url-apis">URL APIs</h3>
<p>URL 由 <code>URL</code> 接口表示，它包含有用的属性如 <code>origin</code> 和 <code>pathname</code>（在浏览器中还有 <code>hash</code>）。这个接口出现在各个地方 — hooks和服务端路由中的 <code>event.url</code>、页面中的 <code>page.url</code>、<code>beforeNavigate</code> 和 <code>afterNavigate</code> 中的 <code>from</code> 和 <code>to</code> 等。</p>
<h4 id="urlsearchparams">URLSearchParams</h4>
<p>无论在哪里遇到 URL，您都可以通过 <code>url.searchParams</code> 访问查询参数，它是 <code>URLSearchParams</code> 的实例：</p>
<pre><code class="language-js">// @filename: ambient.d.ts
declare global {
const url: URL;
}
export {};
// @filename: index.js
// ---cut---
const foo = url.searchParams.get('foo');
</code></pre>
<h3 id="web-加密">Web 加密</h3>
<p>Web Crypto API 通过 <code>crypto</code> 全局对象提供。它在内部用于内容安全策略头部，但您也可以用它来做一些事情，比如生成 UUID：</p>
<pre><code class="language-js">const uuid = crypto.randomUUID();
</code></pre>
<h2 id="svelte-中文文档">Svelte 中文文档</h2>
<p>点击查看中文文档 - SvelteKit 入门指南。</p>
<p>系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！</p>
<p>此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章， 全系列文章目录：https://github.com/mqyqingfeng/Blog</p>
<p>欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。</p><br><br>
来源：https://www.cnblogs.com/yayujs/p/18768477
頁:
[1]