SvelteKit立即开始

项目结构

典型的 SvelteKit 项目如下所示：

¥A typical SvelteKit project looks like this:

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
| ├ service-worker.js
│ └ tracing.server.js
├ static/
│ └ [your static assets]
├ tests/
│ └ [your tests]
├ package.json
├ svelte.config.js
├ tsconfig.json
└ vite.config.js

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

¥You’ll also find common files like .gitignore and .npmrc (and .prettierrc and eslint.config.js and so on, if you chose those options when running npx sv create).

项目文件(Project files)

¥Project files

src

src 目录包含项目的核心内容。除了 src/routes 和 src/app.html 之外的所有内容都是可选的。

¥The src directory contains the meat of your project. Everything except src/routes and src/app.html is optional.

lib 包含你的库代码（实用程序和组件），可以通过 $lib 别名导入，或使用 svelte-package 打包分发

¥lib contains your library code (utilities and components), which can be imported via the $lib alias, or packaged up for distribution using svelte-package
- server 包含你的仅限服务器的库代码。可以使用 $lib/server 别名导入它。SvelteKit 将阻止你在客户端代码中导入这些模块。
  
  ¥server contains your server-only library code. It can be imported by using the $lib/server alias. SvelteKit will prevent you from importing these in client code.
params 包含你的应用所需的任何参数匹配器

¥params contains any param matchers your app needs
routes 包含你的应用的 routes。你还可以在此处共置仅在单个路由中使用的其他组件

¥routes contains the routes of your application. You can also colocate other components that are only used within a single route here
app.html 是你的页面模板 — 包含以下占位符的 HTML 文档：

¥app.html is your page template — an HTML document containing the following placeholders:
- %sveltekit.head% — 应用所需的 <link> 和 <script> 元素，以及任何 <svelte:head> 内容
  
  ¥%sveltekit.head% — <link> and <script> elements needed by the app, plus any <svelte:head> content
- %sveltekit.body% — 渲染页面的标记。这应该存在于 <div> 或其他元素内，而不是直接存在于 <body> 内，以防止由浏览器扩展注入元素而导致的错误，这些元素随后被水化过程破坏。如果不是这种情况，SvelteKit 会在开发过程中向你发出警告
  
  ¥%sveltekit.body% — the markup for a rendered page. This should live inside a <div> or other element, rather than directly inside <body>, to prevent bugs caused by browser extensions injecting elements that are then destroyed by the hydration process. SvelteKit will warn you in development if this is not the case
- %sveltekit.assets% — 如果指定，则为 paths.assets，或 paths.base 的相对路径
  
  ¥%sveltekit.assets% — either paths.assets, if specified, or a relative path to paths.base
- %sveltekit.nonce% — 手动包含的链接和脚本的 CSP nonce（如果使用）
  
  ¥%sveltekit.nonce% — a CSP nonce for manually included links and scripts, if used
- %sveltekit.env.[NAME]% - 这将在渲染时被替换为 [NAME] 环境变量，该变量必须以 publicPrefix（通常是 PUBLIC_）开头。如果不匹配，它将回退到 ''。
  
  ¥%sveltekit.env.[NAME]% - this will be replaced at render time with the [NAME] environment variable, which must begin with the publicPrefix (usually PUBLIC_). It will fallback to '' if not matched.
- %sveltekit.version% — 应用版本，可通过 version 配置指定
  
  ¥%sveltekit.version% — the app version, which can be specified with the version configuration
error.html 是在其他所有方法都失败时渲染的页面。它可以包含以下占位符：

¥error.html is the page that is rendered when everything else fails. It can contain the following placeholders:
- %sveltekit.status% — HTTP 状态
  
  ¥%sveltekit.status% — the HTTP status
- %sveltekit.error.message% — 错误消息
  
  ¥%sveltekit.error.message% — the error message
hooks.client.js 包含你的客户端 hooks

¥hooks.client.js contains your client hooks
hooks.server.js 包含你的服务器 hooks

¥hooks.server.js contains your server hooks
service-worker.js 包含你的服务工作者

¥service-worker.js contains your service worker
instrumentation.server.js 包含你的 observability 设置和插桩代码

¥instrumentation.server.js contains your observability setup and instrumentation code
- 需要适配器支持。如果你的适配器支持，则保证它会在加载和运行你的应用代码之前运行。
  
  ¥Requires adapter support. If your adapter supports it, it is guarnteed to run prior to loading and running your application code.

（项目是否包含 .js 或 .ts 文件取决于你在创建项目时是否选择使用 TypeScript。）

¥(Whether the project contains .js or .ts files depends on whether you opt to use TypeScript when you create your project.)

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

¥If you added Vitest when you set up your project, your unit tests will live in the src directory with a .test.js extension.

static

任何应按原样提供的静态资源（如 robots.txt 或 favicon.png）都在此处。

¥Any static assets that should be served as-is, like robots.txt or favicon.png, go in here.

tests

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

¥If you added Playwright for browser testing when you set up your project, the tests will live in this directory.

package.json

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

¥Your package.json file must include @sveltejs/kit, svelte and vite as devDependencies.

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

¥When you create a project with npx sv create, you’ll also notice that package.json includes "type": "module". This means that .js files are interpreted as native JavaScript modules with import and export keywords. Legacy CommonJS files need a .cjs file extension.

svelte.config.js

此文件包含你的 Svelte 和 SvelteKit configuration。

¥This file contains your Svelte and SvelteKit configuration.

tsconfig.json

如果你在 npx sv create 期间添加了类型检查，则此文件（或 jsconfig.json，如果你更喜欢类型检查的 .js 文件而不是 .ts 文件）会配置 TypeScript。由于 SvelteKit 依赖于以特定方式设置的某些配置，它会生成自己的 .svelte-kit/tsconfig.json 文件，其中包含你自己的配置 extends。要更改顶层选项（例如 include 和 exclude），我们建议扩展生成的配置；有关更多详细信息，请参阅 typescript.config setting。

¥This file (or jsconfig.json, if you prefer type-checked .js files over .ts files) configures TypeScript, if you added typechecking during npx sv create. Since SvelteKit relies on certain configuration being set a specific way, it generates its own .svelte-kit/tsconfig.json file which your own config extends. To make changes to top-level options such as include and exclude, we recommend extending the generated config; see the typescript.config setting for more details.

vite.config.js

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

¥A SvelteKit project is really just a Vite project that uses the @sveltejs/kit/vite plugin, along with any other Vite configuration.

其他文件(Other files)

¥Other files

.svelte-kit

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

¥As you develop and build your project, SvelteKit will generate files in a .svelte-kit directory (configurable as outDir). You can ignore its contents, and delete them at any time (they will be regenerated when you next dev or build).

项目类型 Web 标准