SvelteKit 最新中文文档教程（23）—— CLI 使用指南

前言

Svelte，一个语法简洁、入门容易，面向未来的前端框架。

从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1：

Svelte 以其独特的编译时优化机制著称，具有轻量级 、高性能 、易上手 等特性，非常适合构建轻量级 Web 项目。

为了帮助大家学习 Svelte，我同时搭建了 Svelte 最新的中文文档站点。

如果需要进阶学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

欢迎围观我的"网页版朋友圈"、加入"冴羽·成长陪伴社群"，踏上"前端大佬成长之路"。

概述

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

使用方法

运行 sv 最简单的方式是使用 npx（如果您使用其他包管理器，则使用相应的命令 --- 例如，如果您使用 pnpm，则使用 pnpx）：

bash 复制代码

npx sv <command> <args>

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

致谢

感谢 Christopher Brown，他最初拥有 npm 上的 sv 名称，并慷慨地允许将其用于 Svelte CLI。您可以在 @chbrown/sv 找到原始的 sv 包。

sv create

sv create 用于设置一个新的 SvelteKit 项目，可以选择设置额外功能。

使用方法

bash 复制代码

npx sv create [options] [path]

选项

`--template <name>`

选择使用哪个项目模板：

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

`--types <option>`

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

ts --- 默认使用 .ts 文件，并对 .svelte 组件使用 lang="ts"
jsdoc --- 使用 JSDoc 语法进行类型标注

`--no-types`

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

`--no-add-ons`

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

`--no-install`

跳过依赖安装

sv add

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

使用方法

bash 复制代码

npx sv add

bash 复制代码

npx sv add [add-ons]

您可以从下面的列表中选择多个以空格分隔的插件，或者使用交互式提示。

选项

-C, --cwd --- Svelte(Kit)项目的根目录路径
--no-preconditions --- 跳过检查前置条件
--no-install --- 跳过依赖安装

官方附加组件

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>`

如何显示错误和警告。参见机器可读输出。

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"

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

`--fail-on-warnings`

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

`--compiler-warnings <warnings>`

一个带引号的、逗号分隔的 code:behaviour 对列表，其中 code 是编译器警告代码，behaviour 可以是 ignore 或 error：

bash 复制代码

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

`--diagnostic-sources <sources>`

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

js（包括 TypeScript）
svelte
css

例如：

bash 复制代码

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

`--threshold <level>`

过滤诊断信息：

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

故障排除

查看 language-tools 文档以获取更多关于预处理器设置和其他故障排除的信息。

机器可读输出

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

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

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

sql 复制代码

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

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

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

vbnet 复制代码

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 行，前缀为日志的时间戳。示例：

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 记录。示例：

arduino 复制代码

1590680328921 FAILURE "Connection closed"

致谢

Vue 的 VTI 为 svelte-check 奠定了基础

FAQ

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

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

sv migrate

sv migrate 用于迁移 Svelte(Kit) 代码库。它委托给 svelte-migrate 包来执行。

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

用法

bash 复制代码

npx sv migrate [migration]

迁移选项

`app-state`

将 .svelte 文件中的 $app/store 用法迁移到 $app/state。详情请参阅迁移指南。

`svelte-5`

将 Svelte 4 应用升级到 Svelte 5，并更新各个组件以使用符文和其他 Svelte 5 语法（参见迁移指南）。

`self-closing-tags`

替换 .svelte 文件中所有自闭合的非空元素。详情请参阅这个 PR。

`svelte-4`

将 Svelte 3 应用升级到 Svelte 4（参见迁移指南）。

`sveltekit-2`

将 SvelteKit 1 应用升级到 SvelteKit 2（参见迁移指南）。

`package`

将使用 @sveltejs/package 版本 1 的库升级到版本 2。详情请参阅这个 PR。

`routes`

将预发布版本的 SvelteKit 应用升级以使用 SvelteKit 1 中的文件系统路由约定。详情请参阅这个 PR。

Svelte 中文文档

点击查看中文文档：

系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！

此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章，全系列文章目录：github.com/mqyqingfeng...

欢迎围观我的"网页版朋友圈"、加入"冴羽·成长陪伴社群"，踏上"前端大佬成长之路"。