SvelteKit 最新中文文档教程（23）—— CLI 使用指南
<h2 id="前言">前言</h2><p>Svelte，一个语法简洁、入门容易，面向未来的前端框架。</p>
<p>从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，<strong>从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1</strong>：</p>
<p><img src="https://yayujs-blog.oss-cn-beijing.aliyuncs.com/405488775-48df16b1-939c-489b-8d52-6071869893f0.png"></p>
<p>Svelte 以其独特的编译时优化机制著称，具有<strong>轻量级</strong>、<strong>高性能</strong>、<strong>易上手</strong>等特性，<strong>非常适合构建轻量级 Web 项目</strong>。</p>
<p>为了帮助大家学习 Svelte，我同时搭建了 Svelte 最新的中文文档站点。</p>
<p>如果需要进阶学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！</p>
<p>欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。</p>
<h2 id="概述">概述</h2>
<p>命令行接口 (CLI)，<code>sv</code>，是一个用于创建和维护 Svelte 应用程序的工具包。</p>
<h3 id="使用方法">使用方法</h3>
<p>运行 <code>sv</code> 最简单的方式是使用 <code>npx</code>（如果您使用其他包管理器，则使用相应的命令 — 例如，如果您使用 pnpm，则使用 <code>pnpx</code>）：</p>
<pre><code class="language-bash">npx sv <command> <args>
</code></pre>
<p>如果您在一个已经安装了 <code>sv</code> 的项目中，它将使用本地安装的版本，否则它会下载最新版本并直接运行而无需安装，这对于 <code>sv create</code> 特别有用。</p>
<h3 id="致谢">致谢</h3>
<p>感谢 Christopher Brown，他最初拥有 npm 上的 <code>sv</code> 名称，并慷慨地允许将其用于 Svelte CLI。您可以在 <code>@chbrown/sv</code> 找到原始的 <code>sv</code> 包。</p>
<h2 id="sv-create">sv create</h2>
<p><code>sv create</code> 用于设置一个新的 SvelteKit 项目，可以选择设置额外功能。</p>
<h3 id="使用方法-1">使用方法</h3>
<pre><code class="language-bash">npx sv create
</code></pre>
<h3 id="选项">选项</h3>
<h4 id="--template-name"><code>--template <name></code></h4>
<p>选择使用哪个项目模板：</p>
<ul>
<li><code>minimal</code> — 为新应用提供的基础脚手架</li>
<li><code>demo</code> — 展示应用，包含一个无需 JavaScript 即可运行的猜词游戏</li>
<li><code>library</code> — 用于 Svelte 库的模板，使用 <code>svelte-package</code> 进行设置</li>
</ul>
<h4 id="--types-option"><code>--types <option></code></h4>
<p>是否以及如何为项目添加类型检查：</p>
<ul>
<li><code>ts</code> — 默认使用 <code>.ts</code> 文件，并对 <code>.svelte</code> 组件使用 <code>lang="ts"</code></li>
<li><code>jsdoc</code> — 使用 JSDoc 语法 进行类型标注</li>
</ul>
<h4 id="--no-types"><code>--no-types</code></h4>
<p>阻止添加类型检查。不推荐！</p>
<h4 id="--no-add-ons"><code>--no-add-ons</code></h4>
<p>运行命令时不显示交互式附加功能提示</p>
<h4 id="--no-install"><code>--no-install</code></h4>
<p>跳过依赖安装</p>
<h2 id="sv-add">sv add</h2>
<p><code>sv add</code> 用于为现有项目添加新功能。</p>
<h3 id="使用方法-2">使用方法</h3>
<pre><code class="language-bash">npx sv add
</code></pre>
<pre><code class="language-bash">npx sv add
</code></pre>
<p>您可以从下面的列表中选择多个以空格分隔的插件，或者使用交互式提示。</p>
<h3 id="选项-1">选项</h3>
<ul>
<li><code>-C</code>, <code>--cwd</code> — Svelte(Kit)项目的根目录路径</li>
<li><code>--no-preconditions</code> — 跳过检查前置条件 </li>
<li><code>--no-install</code> — 跳过依赖安装</li>
</ul>
<h3 id="官方附加组件">官方附加组件</h3>
<ul>
<li><code>drizzle</code></li>
<li><code>eslint</code></li>
<li><code>sveltekit-adapter</code></li>
<li><code>lucia</code></li>
<li><code>mdsvex</code></li>
<li><code>paraglide</code></li>
<li><code>playwright</code></li>
<li><code>prettier</code></li>
<li><code>storybook</code></li>
<li><code>tailwindcss</code></li>
<li><code>vitest</code></li>
</ul>
<h2 id="sv-check">sv check</h2>
<p><code>sv check</code> 可以在您的项目中找出错误和警告，例如：</p>
<ul>
<li>未使用的 CSS</li>
<li>可访问性提示</li>
<li>JavaScript/TypeScript 编译器错误</li>
</ul>
<p>需要 Node 16 或更高版本。</p>
<h3 id="安装">安装</h3>
<p>您需要在项目中安装 <code>svelte-check</code> 包：</p>
<pre><code class="language-bash">npm i -D svelte-check
</code></pre>
<h3 id="使用">使用</h3>
<pre><code class="language-bash">npx sv check
</code></pre>
<h3 id="选项-2">选项</h3>
<h4 id="--workspace-path"><code>--workspace <path></code></h4>
<p>工作空间路径。除 <code>node_modules</code> 和那些在 <code>--ignore</code> 中列出的目录外，所有子目录都会被检查。</p>
<h4 id="--output-format"><code>--output <format></code></h4>
<p>如何显示错误和警告。参见机器可读输出。</p>
<ul>
<li><code>human</code></li>
<li><code>human-verbose</code></li>
<li><code>machine</code></li>
<li><code>machine-verbose</code></li>
</ul>
<h4 id="--watch"><code>--watch</code></h4>
<p>保持进程运行并监视更改。</p>
<h4 id="--preservewatchoutput"><code>--preserveWatchOutput</code></h4>
<p>在监视模式下防止屏幕被清除。</p>
<h4 id="--tsconfig-path"><code>--tsconfig <path></code></h4>
<p>传递一个 <code>tsconfig</code> 或 <code>jsconfig</code> 文件的路径。该路径可以相对于工作空间路径或绝对路径。这意味着只有配置文件中 <code>files</code>/<code>include</code>/<code>exclude</code> 模式匹配的文件会被诊断。这也意味着 TypeScript 和 JavaScript 文件的错误会被报告。如果未提供，将从项目目录向上查找下一个 <code>jsconfig</code>/<code>tsconfig.json</code> 文件。</p>
<h4 id="--no-tsconfig"><code>--no-tsconfig</code></h4>
<p>如果您只想检查当前目录及其子目录中的 Svelte 文件，并忽略任何 <code>.js</code>/<code>.ts</code> 文件（它们将不会被类型检查），请使用此选项。</p>
<h4 id="--ignore-paths"><code>--ignore <paths></code></h4>
<p>要忽略的文件/文件夹，相对于工作空间根目录。路径应该用逗号分隔并加引号。例如：</p>
<pre><code class="language-bash">npx sv check --ignore "dist,build"
</code></pre>
<p>仅在与 <code>--no-tsconfig</code> 一起使用时有效。当与 <code>--tsconfig</code> 一起使用时，这只会影响被监视的文件，而不会影响被诊断的文件，后者由 <code>tsconfig.json</code> 决定。</p>
<h4 id="--fail-on-warnings"><code>--fail-on-warnings</code></h4>
<p>如果提供，警告将导致 <code>sv check</code> 以错误代码退出。</p>
<h4 id="--compiler-warnings-warnings"><code>--compiler-warnings <warnings></code></h4>
<p>一个带引号的、逗号分隔的 <code>code:behaviour</code> 对列表，其中 <code>code</code> 是编译器警告代码，<code>behaviour</code> 可以是 <code>ignore</code> 或 <code>error</code>：</p>
<pre><code class="language-bash">npx sv check --compiler-warnings "css_unused_selector:ignore,a11y_missing_attribute:error"
</code></pre>
<h4 id="--diagnostic-sources-sources"><code>--diagnostic-sources <sources></code></h4>
<p>一个用引号括起来的、以逗号分隔的来源列表，这些来源将对你的代码运行诊断。默认情况下，所有来源都处于活动状态：</p>
<ul>
<li><code>js</code>（包括 TypeScript）</li>
<li><code>svelte</code></li>
<li><code>css</code></li>
</ul>
<p>例如：</p>
<pre><code class="language-bash">npx sv check --diagnostic-sources "js,svelte"
</code></pre>
<h4 id="--threshold-level"><code>--threshold <level></code></h4>
<p>过滤诊断信息：</p>
<ul>
<li><code>warning</code>（默认）— 显示错误和警告</li>
<li><code>error</code> — 只显示错误</li>
</ul>
<h3 id="故障排除">故障排除</h3>
<p>查看 language-tools 文档以获取更多关于预处理器设置和其他故障排除的信息。</p>
<h3 id="机器可读输出">机器可读输出</h3>
<p>将 <code>--output</code> 设置为 <code>machine</code> 或 <code>machine-verbose</code> 将以更易于机器读取的方式格式化输出，例如在 CI pipelines 中、代码质量检查等。</p>
<p>每行对应一个新记录。每行由多个列组成，列之间用单个空格字符分隔。每行的第一列包含一个以毫秒为单位的时间戳，可用于监控目的。第二列给出了"行类型"，根据行类型的不同，后续列的数量和类型可能会有所不同。</p>
<p>第一行类型为 <code>START</code>，包含工作空间文件夹（用引号括起）。示例：</p>
<pre><code>1590680325583 START "/home/user/language-tools/packages/language-server/test/plugins/typescript/testfiles"
</code></pre>
<p>随后可能有任意数量的 <code>ERROR</code> 或 <code>WARNING</code> 记录。它们的结构相同，取决于输出参数。</p>
<p>如果参数是 <code>machine</code>，它将告诉我们文件名、起始行和列号，以及错误消息。文件名是相对于工作空间目录的。文件名和消息都用引号括起来。示例：</p>
<pre><code>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`"
</code></pre>
<p>如果参数是 <code>machine-verbose</code>，它将告诉我们文件名、起始行和列号、结束行和列号、错误消息、诊断代码、代码的人类友好描述以及诊断的人类友好来源（例如 svelte/typescript）。文件名相对于工作空间目录。每个诊断表示为一个 ndjson 行，前缀为日志的时间戳。示例：</p>
<pre><code>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"}
</code></pre>
<p>输出以一个 <code>COMPLETED</code> 消息结束，该消息总结了检查期间遇到的文件总数、错误和警告的总数。示例：</p>
<pre><code>1590680326807 COMPLETED 20 FILES 21 ERRORS 1 WARNINGS 3 FILES_WITH_PROBLEMS
</code></pre>
<p>如果应用程序发生运行时错误，这个错误将显示为一条 <code>FAILURE</code> 记录。示例：</p>
<pre><code>1590680328921 FAILURE "Connection closed"
</code></pre>
<h3 id="致谢-1">致谢</h3>
<ul>
<li>Vue 的 VTI 为 <code>svelte-check</code> 奠定了基础</li>
</ul>
<h3 id="faq">FAQ</h3>
<h4 id="为什么没有选项只检查特定文件例如只检查暂存的文件">为什么没有选项只检查特定文件（例如只检查暂存的文件）？</h4>
<p><code>svelte-check</code> 需要"查看"整个项目才能进行有效的检查。假设您重命名了一个组件属性但没有更新使用该属性的所有地方 — 所有使用该属性的地方现在都会出错，但如果只检查更改的文件，你就会遗漏这些错误。</p>
<h2 id="sv-migrate">sv migrate</h2>
<p><code>sv migrate</code> 用于迁移 Svelte(Kit) 代码库。它委托给 <code>svelte-migrate</code> 包来执行。</p>
<p>某些迁移可能会在你的代码库中标注需要完成的任务，你可以通过搜索 <code>@migration</code> 来找到这些任务。</p>
<h3 id="用法">用法</h3>
<pre><code class="language-bash">npx sv migrate
</code></pre>
<h3 id="迁移选项">迁移选项</h3>
<h4 id="app-state"><code>app-state</code></h4>
<p>将 <code>.svelte</code> 文件中的 <code>$app/store</code> 用法迁移到 <code>$app/state</code>。详情请参阅迁移指南。</p>
<h4 id="svelte-5"><code>svelte-5</code></h4>
<p>将 Svelte 4 应用升级到 Svelte 5，并更新各个组件以使用符文 和其他 Svelte 5 语法（参见迁移指南）。</p>
<h4 id="self-closing-tags"><code>self-closing-tags</code></h4>
<p>替换 <code>.svelte</code> 文件中所有自闭合的非空元素。详情请参阅这个 PR。</p>
<h4 id="svelte-4"><code>svelte-4</code></h4>
<p>将 Svelte 3 应用升级到 Svelte 4（参见迁移指南）。</p>
<h4 id="sveltekit-2"><code>sveltekit-2</code></h4>
<p>将 SvelteKit 1 应用升级到 SvelteKit 2（参见迁移指南）。</p>
<h4 id="package"><code>package</code></h4>
<p>将使用 <code>@sveltejs/package</code> 版本 1 的库升级到版本 2。详情请参阅这个 PR。</p>
<h4 id="routes"><code>routes</code></h4>
<p>将预发布版本的 SvelteKit 应用升级以使用 SvelteKit 1 中的文件系统路由约定。详情请参阅这个 PR。</p>
<h2 id="svelte-中文文档">Svelte 中文文档</h2>
<p>点击查看中文文档：</p>
<ol>
<li>概述</li>
<li>sv create</li>
<li>sv add</li>
<li>sv check</li>
<li>sv migrate</li>
</ol>
<p>系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！</p>
<p>此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章， 全系列文章目录：https://github.com/mqyqingfeng/Blog</p>
<p>欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。</p><br><br>
来源：https://www.cnblogs.com/yayujs/p/18844042
頁:
[1]