svelte-cli

Svelte CLI (sv)

何时使用此技能

当用户想要执行以下操作时，请使用此技能：

• 创建新的 SvelteKit 项目（sv create）
• 为现有项目添加集成（使用官方或社区插件的 sv add）
• 对 Svelte 项目运行类型／编译／a11y 诊断（sv check）
• 在不同 Svelte／SvelteKit 版本之间迁移代码库（sv migrate）
• 构建、测试并发布自定义 sv 插件
• 通过 sv-utils 以编程方式读取或编辑 svelte.config.js／vite.config.js

对于常规 Svelte 组件 API 问题、路由约定或 store／状态管理问题，请勿使用此技能——这些问题属于 svelte／sveltekit 技能的范畴。

概述 — 什么是 sv？

sv 是 Svelte 官方的命令行工具包，用于创建和维护 Svelte（SvelteKit）应用。它以 npm 包的形式发布，最好通过 npx／pnpm dlx／bunx／deno run npm:sv 运行：

npm       -> npx sv <command>
pnpm      -> pnpm dlx sv <command>
bun       -> bunx sv <command>
deno      -> deno run npm:sv <command>
yarn      -> yarn dlx sv <command>

如果项目中已将 sv 列为 devDependency，则会使用本地副本；否则会临时下载并运行。

五个子命令：

命令	用途
create	搭建新的 Svelte（Kit）项目 + 可选插件
add	为项目应用插件（官方或社区插件）
check	通过 svelte-check 进行类型／编译／a11y 诊断
migrate	运行代码转换迁移脚本（svelte-migrate）
（编程方式）	sv.create、sv.add、defineAddon、defineAddonOptions

如果运行 npx sv 后似乎没有任何反应，请参阅“快速修复”部分——这是已知的 npm/yarn 行为，本地工具会优先于下载版本。

sv create

npx sv create [options] [path]

搭建新的 SvelteKit 项目。如果省略 path，则使用当前目录（除非传入 --no-dir-check，否则会先检查目录是否为空）。

选项

标志	说明
--from-playground <url>	根据 svelte.dev/playground URL 创建项目
--template <name>	minimal、demo 或 library
--types <option>	ts（默认使用 .ts + lang="ts"）或 jsdoc
--no-types	跳过类型检查
--add [add-ons...]	预先选择插件（语法与 sv add 相同）
--no-add-ons	跳过交互式插件提示
--install <pm>	npm／pnpm／yarn／bun／deno
--no-install	跳过依赖项安装
--no-dir-check	允许目标目录非空

常见调用方式：

npx sv create --template minimal --types ts --add eslint prettier my-app

sv add

npx sv add [add-ons...]     # in a project
npx sv create --add ...     # during project creation

为现有的 Svelte（SvelteKit）项目添加新功能。多个插件可以用空格分隔。如果未传入插件，则会运行交互式提示。

sv add 选项

标志	说明
-C、--cwd <path>	项目根目录
--no-git-check	不对未提交的更改发出警告
--no-download-check	不对社区插件下载发出警告
--install <pm>	npm／pnpm／yarn／bun／deno
--no-install	不安装依赖项

官方插件

将它们作为位置参数传入。选项使用 key:value 语法，并以 + 分隔。

插件	添加内容
better-auth	完整的身份验证配置，使用 Drizzle 适配器；电子邮件/密码身份验证，以及可选的 GitHub OAuth 演示页面
drizzle	为 postgresql / mysql / sqlite 配置 ORM 脚手架，包含 .env，并可选配置 Docker
eslint	ESLint 扁平配置 + eslint-plugin-svelte；与 TS 和 prettier 集成
experimental	选择启用 Svelte/SvelteKit 实验性标志和/或 @next 版本系列
mcp	为 AI Agent 配置 MCP 服务（claude-code、cursor、vscode 等）
mdsvex	Markdown 预处理器（MDX 风格的 Svelte + Markdown）
paraglide	使用 Vite 插件和 reroute / handle hooks 的 Inlang Paraglide i18n
playwright	浏览器测试运行器，包含配置和演示测试
prettier	格式化工具，包含 .prettierrc，并与 eslint 集成
storybook	适用于 SvelteKit 或 Svelte+Vite 的 Storybook
sveltekit-adapter	适配器（auto、node、static、vercel、cloudflare、netlify）
tailwindcss	Tailwind v4 Vite 插件，并与 prettier 集成
vitest	原生 Vite 测试，支持单元测试/组件测试模式

带选项的示例：

npx sv add tailwindcss="plugins:typography,forms"
npx sv add drizzle="database:postgresql+client:postgres.js+docker:yes"
npx sv add sveltekit-adapter="adapter:cloudflare+cfTarget:workers"

社区插件

社区插件为实验性功能。API 可能会发生变化。Svelte 维护者尚未审查社区插件是否含有恶意代码。

社区插件是带有 sv-add 关键词的 npm 包。可通过组织名称（会查找 @org/sv）、完整包名称、file: 路径或版本来引用：

npx sv add @supacool                            # npm org lookup
npx sv add @my-org/[email protected]                     # pinned version
npx sv add file:../path/to/my-addon             # local add-on
npx sv add eslint @supacool                     # mix official + community
npx sv create --add eslint @supacool my-app

在 Windows PowerShell 中，使用引号转义 @：npx sv add '@supacool'。

sv check

npm i -D svelte-check
npx sv check

运行 svelte-check：检测 .svelte、.svelte.ts、.svelte.js 文件中的未使用 CSS、a11y 问题以及 JS/TS 编译错误。需要 Node 16+。

选项

标志	说明
--workspace <path>	要扫描的工作区（默认为项目根目录）
--output <format>	human、human-verbose、machine、machine-verbose
--watch	持续运行，并在发生更改时重新检查
--preserveWatchOutput	监视模式下不清除屏幕
--tsconfig <path>	使用指定的 tsconfig/jsconfig
--no-tsconfig	完全跳过 .ts/.js 文件
--ignore <paths>	以逗号分隔的要忽略的路径（与 --no-tsconfig 配合使用）
--fail-on-warnings	有警告时以非零状态码退出
--compiler-warnings <pairs>	code:behaviour 对，例如 css_unused_selector:ignore
--diagnostic-sources <sources>	js（包括 TS）、svelte、css
--threshold <level>	仅显示 warning（默认）或 error

机器可读输出

--output machine 和 --output machine-verbose 会生成由空格/JSON 分隔的行流：

1590680325583 START "/path/to/workspace"
1590680326283 ERROR "codeaction.svelte" 1:16 "Cannot find module 'blubb'..."
1590680326778 WARNING "imported-file.svelte" 0:37 "Component has unused export property..."
1590680326807 COMPLETED 20 FILES 21 ERRORS 1 WARNINGS 3 FILES_WITH_PROBLEMS
1590680328921 FAILURE "Connection closed"   # only on runtime error

machine-verbose 变体会输出 ndjson，其中包含 start / end 位置、code、source 和完整描述。

svelte-check 不支持“仅检查暂存文件”模式——要确保跨文件类型错误检查有效，它必须检查整个项目。

sv migrate

npx sv migrate                 # interactive picker
npx sv migrate [migration]     # run a specific codemod

此命令会调用 svelte-migrate。部分迁移会在代码中添加 // @migration TODO，需要你手动完成。

迁移	用途
app-state	在 .svelte 文件中将 $app/stores -> $app/state（SvelteKit 2.12+）
svelte-5	Svelte 4 -> 5：将组件转换为使用符文（$state、$derived、$effect、$props 等）
self-closing-tags	替换 .svelte 文件中非空元素的自闭合标签
svelte-4	Svelte 3 -> 4
sveltekit-2	SvelteKit 1 -> 2
package	@sveltejs/package v1 -> v2（库作者）
routes	将预发布版 SvelteKit -> SvelteKit 1 文件系统路由

运行迁移前务必先提交，这样你就可以比较差异并还原更改。

自定义插件（程序化 API）

两个包构成插件系统：

• sv — 负责何时何地：工作区检测、文件 I/O、依赖跟踪、插件编排。
• @sveltejs/sv-utils — 负责具体内容：纯解析器、AST 转换、语言辅助工具。不感知文件系统。

自定义插件的基本骨架：

import { transforms } from '@sveltejs/sv-utils';
import { defineAddon, defineAddonOptions } from 'sv';

export default defineAddon({
  id: 'my-addon',
  shortDescription: 'says hello',
  options: defineAddonOptions()
    .add('who', { question: 'To whom?', type: 'string' })
    .build(),
  setup: ({ dependsOn, isKit, unsupported }) => {
    if (!isKit) unsupported('Requires SvelteKit');
    dependsOn('vitest');
  },
  run: ({ sv, options, directory }) => {
    sv.file(
      directory.kitRoutes + '/+page.svelte',
      transforms.svelte(({ ast, svelte }) => {
        svelte.addFragment(ast, `<p>Hello ${options.who}!</p>`);
      })
    );
  },
  nextSteps: ({ options }) => [`Greet ${options.who}!`]
});

引导、打包（tsdown）、发布（需要 npm 组织）、测试（sv/testing 的 createSetupTest）和 package.json 规则，详见 references/custom-addon-reference.md。

sv-utils（面向插件作者的底层 API）

@sveltejs/sv-utils 目前处于实验阶段，但为插件通常会编辑的每种文件类型提供了支持解析器的转换功能。

转换

每个转换都是一个柯里化函数 — 传入回调后，会得到一个 (content) => content 函数，可直接传给 sv.file()。

转换	回调接收的内容	用途
transforms.script	{ ast, comments, content, js }	.js / .ts 文件
transforms.svelte	{ ast, content, svelte, js }	.svelte 组件
transforms.svelteScript(opts, cb)	{ ast, content, svelte, js }（ast.instance 始终非 null）	需要确保存在 <script> 的组件
transforms.css	{ ast, content, css }	.css 文件
transforms.json	{ data, content, json }	package.json、tsconfig.json
transforms.yaml / transforms.toml	{ data, content }	配置文件
transforms.text	{ content, text }	.env、.gitignore

从回调返回 false 可中止操作 — 保留原始内容。完整的 js.* / css.* / svelte.* / json.* / html.* / text.* 辅助工具命名空间详见 references/sv-utils-reference.md。

Svelte 配置辅助工具

SvelteKit 配置可以位于 vite.config.{js,ts} 中（通过 sveltekit() 插件参数），也可以位于 svelte.config.{js,ts} 中。svelteConfig.edit 会透明地写入这两种配置 — 无需自行处理 kit 嵌套：

import { svelteConfig } from '@sveltejs/sv-utils';

svelteConfig.edit({ sv, cwd }, ({ ast, property, override, js }) => {
  // svelte-level option
  js.array.append(property('extensions', { fallback: js.array.create() }), '.svx');
  // kit option
  override({ adapter: js.functions.createCall({ name: 'adapter', args: [], useIdentifiers: true }) });
});

svelteConfig.find(read) 返回 { path, kind }（'vite' 或 'svelte'）；svelteConfig.read(read) 返回 { location, config, kit } 对象表达式。

包管理器辅助工具

pnpm.allowBuilds('pkg-name') 返回一个针对 pnpm-workspace.yaml 的转换，用于将包添加到 pnpm 的 allow-builds 配置中。它会检测已安装的 pnpm 版本：

• pnpm >= 11 -> 统一的 allowBuilds: { pkg: true } 映射
• pnpm < 11 -> 旧版 onlyBuiltDependencies 列表

if (packageManager === 'pnpm') {
  sv.file(file.findUp('pnpm-workspace.yaml'), pnpm.allowBuilds('esbuild'));
}

常见问题修复

• npx sv 没有任何操作 — npm/yarn 会优先使用本地安装的工具。解决方法：

  • 使用 npm exec sv ... 或 npx --yes sv ...
  • 在 Windows PowerShell 中，sv 与 Set-Variable 别名冲突 — 参见 sveltejs/cli#317。
  • 在 Linux 中，sv 可能与 runit 冲突 — 参见 sveltejs/cli#259。
  • 确认：npx --yes sv --version 应输出一个版本号。

• 找不到 sv check — 请先安装 svelte-check：npm i -D svelte-check。

• sv add @community 在 PowerShell 上报错 — 请将参数加上引号：npx sv add '@supacool'。

• 迁移留下了 @migration TODO — 这些需要手动跟进；搜索 // @migration 并完成相应工作。

• sv add 因 git 工作区不干净而拒绝执行 — 如果你有意在不干净的工作树上操作，请传入 --no-git-check。

• svelte-check 检查 JS/TS 文件失败 — 请提供 --tsconfig，或使用 --no-tsconfig 完全跳过这些文件。

• sv add file:../path 未能获取更改 — demo-add 脚本会自动重新构建；否则，请重新打包插件后再运行。

注意事项

• 社区附加组件 API 仍处于实验阶段，可能会发生变化。请在 peerDependencies 中固定 sv 版本（例如 "sv": "^0.13.0"）。
• 社区附加组件包必须发布在 npm 组织下（@org/...）——my-lib 这类普通名称会被拒绝。
• 包名中的 sv 作用域会自动解析：npx sv add @my-org == npx sv add @my-org/sv。
• 对于捆绑的附加组件，tsdown 是标准工具。CLI 会先查找 ./sv，再查找 .——因此，同时导出其他功能的包应通过 ./sv 子路径公开附加组件。
• sv check 无法只检查部分文件（例如，仅检查暂存文件）。要确保跨文件类型错误检查有效，必须检查整个项目。
• --ignore 只有与 --no-tsconfig 搭配时才会对文件监视器生效；使用 --tsconfig 时，忽略规则由配置中的 exclude 决定。
• svelteConfig.edit 会通过 sv.file 写入，因此该编辑会与所有其他更改一起显示在同一差异中——不要通过手动读取和写入文件来绕过它。
• transforms.yaml / transforms.toml 会原地修改 data——返回值会被忽略。
• pnpm < 11 和 >= 11 使用不同的“允许构建”模式——辅助工具会处理这两种情况，但如果你直接编写配置，请遵循对应的版本逻辑。

常见问题

问：如何使用各个包管理器运行 sv？

包管理器	命令
npm	npx sv create
pnpm	pnpm dlx sv create
Bun	bunx sv create
Deno	deno run npm:sv create
Yarn	yarn dlx sv create

问：我可以在已安装 sv 的项目中运行 sv 吗？

可以。如果本地已安装，npx sv ... 会使用本地副本；否则会临时下载最新版本。因此，无需先安装就能运行 sv create。

问：sv check --output 中的 machine 和 machine-verbose 有什么区别？

两者都会输出 START / ERROR / WARNING / COMPLETED / FAILURE 行。machine 的列为：时间戳、类型、文件名、行:列、消息。machine-verbose 还会添加结束位置、诊断代码和来源——每行均为 ndjson。

问：安装社区附加组件安全吗？

Svelte 维护者不会审核这些附加组件。安装风险自负。--no-download-check 会抑制警告，但不会增加任何安全保障。

问：可以使用 sv check 仅检查暂存文件吗？

不可以。svelte-check 需要整个项目图。只检查部分文件会漏掉未更改文件中已重命名属性的用法。

问：svelte.config.js 应放在哪里？

可以放在 vite.config.{js,ts} 中（传递给 sveltekit() 插件），也可以单独放在 svelte.config.{js,ts} 文件中。sv create 会将其放在 vite.config.js 中。svelteConfig.edit 会透明地处理这两种情况。

问：自定义附加组件所需的最低 sv peer dependency 版本是什么？

根据代码使用的功能确定——在 package.json 的 peerDependencies 中设置。若已安装的 sv 主版本不同，用户会收到兼容性警告。参考附加组件以 sv@^0.13.0 为目标版本。

问：为什么 sv add 会警告存在未提交的更改？

因为它会修改多个项目文件。此警告用于提供安全保障；传入 --no-git-check 可跳过检查。