SvelteKit中文1-开始

svelte,sveltekit

字数统计: 2.6k阅读时长: 10 min

 2023/04/25 

该系列文章一共四篇，以下是系列文章链接：

SvelteKit中文1-开始
SvelteKit中文2-核心概念
 SvelteKit中文3-编译发布
 SvelteKit中文4-高级概念

介绍

如果您是Svelte或SvelteKit的新手，我们建议您查看交互式教程。

如果遇到困难，请在Discord聊天室寻求帮助。

什么是SvelteKit?

SvelteKit是一个使用Svelte快速开发强大、高性能Web应用程序的框架。如果你来自React，SvelteKit类似于Next。如果你来自Vue，SvelteKit类似于Nuxt。

什么是Svelte?

简而言之，Svelte 是一种编写用户界面组件的方式——例如导航栏、评论区或联系表单——这些组件在用户浏览器中可见并与其交互。Svelte 编译器将您的组件转换为 JavaScript 代码，可以运行以呈现页面的 HTML 和样式化页面的 CSS。您不需要了解 Svelte 就能理解本指南的其余部分，但它会有所帮助。如果您想了解更多，请查看 Svelte 教程。

SvelteKit 在 Svelte 的基础上提供了什么？

Svelte 渲染 UI 组件。您可以使用 Svelte 组合这些组件并渲染整个页面，但编写完整应用程序需要的不仅是 Svelte。

SvelteKit 提供了基本功能，如路由器 - 即在单击链接时更新 UI，并提供服务器端渲染（SSR）。但除此之外，使用所有现代最佳实践构建应用程序非常复杂。这些实践包括构建优化，以便只加载所需的最小代码；离线支持；在用户启动导航之前预加载页面；可配置的呈现方式，允许您在服务器端进行 SSR、在浏览器客户端进行客户端呈现或者通过预渲染来构建时呈现应用程序的不同部分等等。SvelteKit 为您处理所有繁琐的事情，使您可以专注于创造性工作。

它利用带有 Svelte 插件的 Vite 进行模块热替换（HMR），从而立即反映浏览器中代码更改，并提供快速且功能丰富的开发体验。

创建一个Project

开始构建 SvelteKit 应用程序的最简单方法是运行 npm create:

npm create svelte@latest my-app
cd my-app
npm install
npm run dev

第一个命令将在my-app目录中搭建一个新项目，并询问您是否想设置一些基本工具，例如TypeScript。有关设置其他工具的指针，请参阅常见问题解答。随后的命令将安装其依赖项并在localhost:5173上启动服务器。

有两个基本概念：

你的应用程序中每个页面都是一个 Svelte 组件
通过将文件添加到项目的 src/routes 目录来创建页面。这些页面将被服务器渲染，以便用户首次访问您的应用程序时尽可能快地加载，然后客户端应用程序接管。

尝试编辑文件以了解所有内容如何工作。

编译器安装

我们建议使用带有Svelte扩展的Visual Studio Code（也称为VS Code），但是还支持许多其他编辑器。

项目结构

一个典型的SvelteKit项目的目录结构看起来是这样的:

my-project/
├ src/
│ ├ lib/
│ │ ├ server/
│ │ │ └ [your server-only lib files]
│ │ └ [your lib files]
│ ├ params/
│ │ └ [your param matchers]
│ ├ routes/
│ │ └ [your routes]
│ ├ app.html
│ ├ error.html
│ ├ hooks.client.js
│ └ hooks.server.js
├ static/
│ └ [your static assets]
├ tests/
│ └ [your tests]
├ package.json
├ svelte.config.js
├ tsconfig.json
└ vite.config.js

如果您在运行npm create svelte@latest时选择了这些选项，您还会找到常见的文件，例如.gitignore和.npmrc（以及.prettierrc和.eslintrc.cjs等）

项目文件

src

src目录包含了你的项目主要内容。除了src/routes和src/app.html之外，其他都是可选的。

lib 包含您的库代码（实用程序和组件），可以通过 $lib 别名导入，或使用 svelte-package 打包以进行分发
- server 包含仅限服务器的库代码。可以使用 $lib/server 别名导入。SvelteKit 将防止您在客户端代码中导入这些内
params 包含应用程序所需的任何参数匹配器
routes 包含应用程序的路由。您还可以将其他仅在单个路由中使用的组件放置在此处
app.html 是页面模板 - 一个 HTML 文档，其中包含以下占位符：
- %sveltekit.head% - 应用程序需要的 <link> 和 <script> 元素，以及任何<svelte:head>内容
- %sveltekit.body% - 渲染页面的标记。这应该位于 <div> 或其他元素内部，而不是直接位于 <body> 内部，以避免浏览器扩展注入然后被水合过程销毁引起错误。如果不是这种情况，则 SvelteKit 在开发时会警告您。
- %sveltekit.assets% - 如果指定了 paths.assets，则为 paths.assets 的路径；否则为相对路径到 paths.base
- %sveltekit.nonce% - 如果使用，则为手动包括链接和脚本提供 CSP nonce
- %sveltekit.env.[NAME]%- 这将在渲染时替换为 [NAME] 环境变量，它必须以 publicPrefix（通常为 PUBLIC_）开头。如果不匹配，则会回退到 ‘’。
error.html 是在其他所有内容失败时呈现的页面。它可以包含以下占位符：
- %sveltekit.status% - HTTP 状态
- %sveltekit.error.message% - 错误消息
hooks.client.js 包含您的客户端钩子
hooks.server.js 包含您的服务器钩子
service-worker.js 包含您的服务工作者

（项目是否包含.js或.ts文件取决于您创建项目时选择使用TypeScript。您可以在本页面底部的切换中在文档之间切换JavaScript和TypeScript。）

如果您在设置项目时添加了Vitest，则单元测试将位于src目录中，并带有.test.js扩展名。

static

任何应该原样提供的静态资源，例如robots.txt 或 favicon.png，请放在此处。

tests

如果您在设置项目时添加了 Playwright 进行浏览器测试，则测试将存储在此目录中。

package.json

你的 package.json 文件必须包含 @sveltejs/kit、svelte 和 vite 作为 devDependencies。

当你使用 npm create svelte@latest 创建项目时，你会注意到 package.json 包括 "type": "module"。这意味着 .js 文件被解释为具有 import 和 export 关键字的本地 JavaScript 模块。传统的 CommonJS 文件需要一个 .cjs 的文件扩展名。

svelte.config.js

该文件包含您的 Svelte 和 SvelteKit 配置。

tsconfig.json

该文件（或 jsconfig.json，如果您更喜欢对.js文件进行类型检查而不是 .ts 文件）配置了 TypeScript，如果您在 npm create svelte@latest 期间添加了类型检查。由于 SvelteKit 需要特定的配置方式，因此它会生成自己的 .svelte-kit/tsconfig.json 文件，并且您自己的配置extends。

vite.config.js

一个 SvelteKit 项目实际上只是一个使用了 @sveltejs/kit/vite 插件以及其他 Vite 配置的 Vite 项目。

其他文件

.svelte-kit

在开发和构建项目时，SvelteKit 会在 .svelte-kit 目录中生成文件（可以配置为 outDir）。您可以忽略其内容，并随时删除它们（下次进行 dev 或 build 时将重新生成它们）。

Web标准

在整个文档中，您会看到对 SvelteKit 构建在其之上的标准 Web API 的引用。我们不是重复造轮子，而是使用平台，这意味着您现有的 Web 开发技能也适用于 SvelteKit。相反地，学习 SvelteKit 将帮助您成为其他领域更好的 Web 开发人员。

这些 API 在所有现代浏览器和许多非浏览器环境（如 Cloudflare Workers、Deno 和 Vercel Edge Functions）中都可用。在开发过程中，在基于 Node 的环境（包括 AWS Lambda）的适配器中，在必要时通过 polyfills 提供支持（目前是这样 - Node 正在快速添加对更多 Web 标准的支持）。

特别是，您将熟悉以下内容：

Fetch APIs

SvelteKit 使用 fetch 从网络获取数据。它在钩子、服务器路由以及浏览器中都可用。

在load函数、服务器钩子和 API 路由中，有一种特殊版本的 fetch 可以直接在服务器端渲染期间调用端点，而无需进行 HTTP 调用，并保留凭据。（要在 load 之外的服务器端代码中进行带凭据的 fetch，请显式传递 cookie 和/或authorization。）它还允许您发出相对请求，而服务器端 fetch 通常需要完全限定的 URL。

除了 fetch 本身之外，Fetch API 还包括以下接口：

Request

Request的实例可以在钩子和服务器路由中作为event.request访问。它包含有用的方法，如request.json()和request.formData()，用于获取发布到端点的数据。

Response

从 await fetch(...) 和 +server.js 文件中的处理程序返回 Response 的实例。从根本上说，SvelteKit 应用程序是将Request转换为Response的机器。

Headers

Headers接口允许您读取传入的request.headers并设置传出的response.headers:

src/routes/what-is-my-user-agent/+server.js

import { json } from '@sveltejs/kit';


/** @type {import('./$types').RequestHandler} */
export function GET(event) {
    // log all headers
    console.log(...event.request.headers);


    return json({
        // retrieve a specific header
        userAgent: event.request.headers.get('user-agent')
    });
}

FormData

处理HTML本地表单提交时，您将使用FormData对象。

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();


    // log all fields
    console.log([...body]);


    return json({
        // get a specific field's value
        name: body.get('name') ?? 'world'
    });
}

Stream APIs

大多数情况下，您的端点将返回完整数据，就像上面的userAgent示例一样。有时候，您可能需要返回一个太大而无法一次性放入内存或以块传递的响应，在这种情况下平台提供了流——ReadableStream、WritableStream和TransformStream。

URL APIs

URL由URL接口表示，其中包括有用的属性，如origin和pathname（在浏览器中还有hash）。此接口出现在各种地方 - 钩子和服务器路由中的event.url，页面中的$page.url，在beforeNavigate和afterNavigate中的from和to等。

URLSearchParams

无论在哪里遇到URL，您都可以通过url.searchParams访问查询参数，它是URLSearchParams的一个实例：

1	const foo = url.searchParams.get('foo');

Web Crypto

Web Crypto API 可通过全局变量 crypto 使用。它在内容安全策略标头内部使用，但您也可以将其用于生成 UUID 等其他操作：

1	const uuid = crypto.randomUUID();