SvelteKit入门指南

项目结构

一个典型的 SvelteKit 项目结构如下：

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

您还会发现一些常见文件，如 .gitignore 和 .npmrc（如果您在运行 npx sv create 时选择了这些选项，还会有 .prettierrc 和 eslint.config.js 等）。

项目文件

src

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

lib 包含您的库代码（实用工具和组件），可以通过 $lib 别名导入，或使用 svelte-package 打包分发
- server 包含您的仅服务端（server-only）库代码。可以使用 $lib/server 别名导入。SvelteKit 会阻止您在客户端代码中导入这些内容。
params 包含应用需要的任何参数匹配器
routes 包含应用的路由。您也可以在这里放置仅在单个路由中使用的其他组件
app.html 是您的页面模板 — 一个包含以下占位符的 HTML 文档：
- %sveltekit.head% — 应用需要的 <link> 和 <script> 元素，以及任何 <svelte:head> 内容
- %sveltekit.body% — 渲染页面的标记。这应该放在 <div> 或其他元素内，而不是直接放在 <body> 内，以防止浏览器插件注入元素后被水合过程销毁而导致的错误。如果不是这样情况，SvelteKit 会在开发时警告您
- %sveltekit.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 包含您的 service worker

（项目是包含 .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。

当您使用 npx sv create 创建项目时，您会注意到 package.json 包含了 "type": "module"。这意味着 .js 文件将被解释为带有 import 和 export 关键字的原生 JavaScript 模块。遗留的 CommonJS 文件需要一个 .cjs 文件扩展名。

svelte.config.js

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

tsconfig.json

如果您在 npx sv create 期间添加了类型检查，此文件（或者如果您更喜欢对 .js 文件而不是 .ts 文件进行类型检查，则为 jsconfig.json）将配置 TypeScript。由于 SvelteKit 依赖于某些特定方式的配置设置，它会生成自己的 .svelte-kit/tsconfig.json 文件，您的配置将 extends 这个文件。

vite.config.js

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

其他文件

.svelte-kit

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

在 GitHub 编辑此页面

创建项目 Web 标准