<SYSTEM>This is the developer documentation for the Svelte CLI.</SYSTEM>


# 概述

命令行接口 (CLI)，`sv`，是一个用于创建和维护 Svelte 应用程序的工具包。

## 使用方法

运行 `sv` 最简单的方式是使用 [`npx`](https://docs.npmjs.com/cli/v8/commands/npx)（如果您使用其他包管理器，则使用相应的命令 — 例如，如果您使用 [pnpm](https://pnpm.io/)，则使用 `pnpx`）：

```bash
npx sv <command> <args>
```

如果您在一个已经安装了 `sv` 的项目中，它将使用本地安装的版本，否则它会下载最新版本并直接运行而无需安装，这对于 [`sv create`](sv-create) 特别有用。

## 致谢

感谢 [Christopher Brown](https://github.com/chbrown)，他最初拥有 npm 上的 `sv` 名称，并慷慨地允许将其用于 Svelte CLI。您可以在 [`@chbrown/sv`](https://www.npmjs.com/package/@chbrown/sv) 找到原始的 `sv` 包。

# sv create

`sv create` 用于设置一个新的 SvelteKit 项目，可以选择[设置额外功能](sv-add#Official-add-ons)。

## 使用方法

```bash
npx sv create [options] [path]
```

## 选项

### `--template <name>`

选择使用哪个项目模板：

- `minimal` — 为新应用提供的基础脚手架
- `demo` — 展示应用，包含一个无需 JavaScript 即可运行的猜词游戏
- `library` — 用于 Svelte 库的模板，使用 `svelte-package` 进行设置

### `--types <option>`

是否以及如何为项目添加类型检查：

- `ts` — 默认使用 `.ts` 文件，并对 `.svelte` 组件使用 `lang="ts"`
- `jsdoc` — 使用 [JSDoc 语法](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) 进行类型标注

### `--no-types`

阻止添加类型检查。不推荐！

### `--no-add-ons`

运行命令时不显示交互式附加功能提示

### `--no-install`

跳过依赖安装

<!-- ## 程序化接口

```js
// TODO: 这里在文档站点中未注释时会产生类型检查错误。需要发布 sv，在站点中安装它，然后取消注释。
// import { create } from 'sv';

// // todo: 检查这是否正确
// create(cwd, {
// 	// 在此添加你的选项
// 	// todo: 列出可用选项
// });
```
-->

# sv add

`sv add` 用于为现有项目添加新功能。

## 使用方法

```bash
npx sv add
```

```bash
npx sv add [add-ons]
```

您可以从[下面的列表](#Official-add-ons)中选择多个以空格分隔的插件，或者使用交互式提示。

## 选项

- `-C`, `--cwd` — Svelte(Kit)项目的根目录路径
- `--no-preconditions` — 跳过检查前置条件 <!-- TODO 这是什么意思？ -->
- `--no-install` — 跳过依赖安装

## 官方附加组件

<!-- TODO 这应该是一个单独的部分，这些每一个都应该有自己的页面 -->

- `drizzle`
- `eslint`
- `sveltekit-adapter`
- `lucia`
- `mdsvex`
- `paraglide`
- `playwright`
- `prettier`
- `storybook`
- `tailwindcss`
- `vitest`

# sv check

`sv check` 可以在您的项目中找出错误和警告，例如：

- 未使用的 CSS
- 可访问性提示
- JavaScript/TypeScript 编译器错误

需要 Node 16 或更高版本。

## 安装

您需要在项目中安装 `svelte-check` 包：

```bash
npm i -D svelte-check
```

## 使用

```bash
npx sv check
```

## 选项

### `--workspace <path>`

工作空间路径。除 `node_modules` 和那些在 `--ignore` 中列出的目录外，所有子目录都会被检查。

### `--output <format>`

如何显示错误和警告。参见[机器可读输出](#Machine-readable-output)。

- `human`
- `human-verbose`
- `machine`
- `machine-verbose`

### `--watch`

保持进程运行并监视更改。

### `--preserveWatchOutput`

在监视模式下防止屏幕被清除。

### `--tsconfig <path>`

传递一个 `tsconfig` 或 `jsconfig` 文件的路径。该路径可以相对于工作空间路径或绝对路径。这意味着只有配置文件中 `files`/`include`/`exclude` 模式匹配的文件会被诊断。这也意味着 TypeScript 和 JavaScript 文件的错误会被报告。如果未提供，将从项目目录向上查找下一个 `jsconfig`/`tsconfig.json` 文件。

### `--no-tsconfig`

如果您只想检查当前目录及其子目录中的 Svelte 文件，并忽略任何 `.js`/`.ts` 文件（它们将不会被类型检查），请使用此选项。

### `--ignore <paths>`

要忽略的文件/文件夹，相对于工作空间根目录。路径应该用逗号分隔并加引号。例如：

```bash
npx sv check --ignore "dist,build"
```

<!-- TODO what the hell does this mean? is it possible to use --tsconfig AND --no-tsconfig? if so what would THAT mean? -->

仅在与 `--no-tsconfig` 一起使用时有效。当与 `--tsconfig` 一起使用时，这只会影响被监视的文件，而不会影响被诊断的文件，后者由 `tsconfig.json` 决定。

### `--fail-on-warnings`

如果提供，警告将导致 `sv check` 以错误代码退出。

### `--compiler-warnings <warnings>`

一个带引号的、逗号分隔的 `code:behaviour` 对列表，其中 `code` 是[编译器警告代码](../svelte/compiler-warnings)，`behaviour` 可以是 `ignore` 或 `error`：

```bash
npx sv check --compiler-warnings "css_unused_selector:ignore,a11y_missing_attribute:error"
```

### `--diagnostic-sources <sources>`

一个用引号括起来的、以逗号分隔的来源列表，这些来源将对你的代码运行诊断。默认情况下，所有来源都处于活动状态：

<!-- TODO would be nice to have a clearer definition of what these are -->

- `js`（包括 TypeScript）
- `svelte`
- `css`

例如：

```bash
npx sv check --diagnostic-sources "js,svelte"
```

### `--threshold <level>`

过滤诊断信息：

- `warning`（默认）— 显示错误和警告
- `error` — 只显示错误

## 故障排除

[查看 language-tools 文档](https://github.com/sveltejs/language-tools/blob/master/docs/README.md)以获取更多关于预处理器设置和其他故障排除的信息。

## 机器可读输出

将 `--output` 设置为 `machine` 或 `machine-verbose` 将以更易于机器读取的方式格式化输出，例如在 CI pipelines 中、代码质量检查等。

每行对应一个新记录。每行由多个列组成，列之间用单个空格字符分隔。每行的第一列包含一个以毫秒为单位的时间戳，可用于监控目的。第二列给出了"行类型"，根据行类型的不同，后续列的数量和类型可能会有所不同。

第一行类型为 `START`，包含工作空间文件夹（用引号括起）。示例：

```
1590680325583 START "/home/user/language-tools/packages/language-server/test/plugins/typescript/testfiles"
```

随后可能有任意数量的 `ERROR` 或 `WARNING` 记录。它们的结构相同，取决于输出参数。

如果参数是 `machine`，它将告诉我们文件名、起始行和列号，以及错误消息。文件名是相对于工作空间目录的。文件名和消息都用引号括起来。示例：

```
1590680326283 ERROR "codeactions.svelte" 1:16 "Cannot find module 'blubb' or its corresponding type declarations."
1590680326778 WARNING "imported-file.svelte" 0:37 "Component has unused export property 'prop'. If it is for external reference only, please consider using `export const prop`"
```

如果参数是 `machine-verbose`，它将告诉我们文件名、起始行和列号、结束行和列号、错误消息、诊断代码、代码的人类友好描述以及诊断的人类友好来源（例如 svelte/typescript）。文件名相对于工作空间目录。每个诊断表示为一个 [ndjson](https://en.wikipedia.org/wiki/JSON_streaming#Newline-Delimited_JSON) 行，前缀为日志的时间戳。示例：

```
1590680326283 {"type":"ERROR","fn":"codeaction.svelte","start":{"line":1,"character":16},"end":{"line":1,"character":23},"message":"Cannot find module 'blubb' or its corresponding type declarations.","code":2307,"source":"js"}
1590680326778 {"type":"WARNING","filename":"imported-file.svelte","start":{"line":0,"character":37},"end":{"line":0,"character":51},"message":"Component has unused export property 'prop'. If it is for external reference only, please consider using `export
const prop`","code":"unused-export-let","source":"svelte"}
```

输出以一个 `COMPLETED` 消息结束，该消息总结了检查期间遇到的文件总数、错误和警告的总数。示例：

```
1590680326807 COMPLETED 20 FILES 21 ERRORS 1 WARNINGS 3 FILES_WITH_PROBLEMS
```

如果应用程序发生运行时错误，这个错误将显示为一条 `FAILURE` 记录。示例：

```
1590680328921 FAILURE "Connection closed"
```

## 致谢

- Vue 的 [VTI](https://github.com/vuejs/vetur/tree/master/vti) 为 `svelte-check` 奠定了基础

## FAQ

### 为什么没有选项只检查特定文件（例如只检查暂存的文件）？

`svelte-check` 需要"查看"整个项目才能进行有效的检查。假设您重命名了一个组件属性但没有更新使用该属性的所有地方 — 所有使用该属性的地方现在都会出错，但如果只检查更改的文件，你就会遗漏这些错误。

# sv migrate

`sv migrate` 用于迁移 Svelte(Kit) 代码库。它委托给 [`svelte-migrate`](https://www.npmjs.com/package/svelte-migrate) 包来执行。

某些迁移可能会在你的代码库中标注需要完成的任务，你可以通过搜索 `@migration` 来找到这些任务。

## 用法

```bash
npx sv migrate [migration]
```

## 迁移选项

### `app-state`

将 `.svelte` 文件中的 `$app/store` 用法迁移到 `$app/state`。详情请参阅[迁移指南](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated)。

### `svelte-5`

将 Svelte 4 应用升级到 Svelte 5，并更新各个组件以使用[符文](../svelte/what-are-runes) 和其他 Svelte 5 语法（[参见迁移指南](../svelte/v5-migration-guide)）。

### `self-closing-tags`

替换 `.svelte` 文件中所有自闭合的非空元素。详情请参阅这个 [PR](https://github.com/sveltejs/kit/pull/12128)。

### `svelte-4`

将 Svelte 3 应用升级到 Svelte 4（[参见迁移指南](../svelte/v4-migration-guide)）。

### `sveltekit-2`

将 SvelteKit 1 应用升级到 SvelteKit 2（[参见迁移指南](../kit/migrating-to-sveltekit-2)）。

### `package`

将使用 `@sveltejs/package` 版本 1 的库升级到版本 2。详情请参阅这个 [PR](https://github.com/sveltejs/kit/pull/8922)。

### `routes`

将预发布版本的 SvelteKit 应用升级以使用 SvelteKit 1 中的文件系统路由约定。详情请参阅这个 [PR](https://github.com/sveltejs/kit/discussions/5774)。