Svelte 官方 FAQ 详解：从入门路径到样式作用域、测试与移动端支持的权威答案

本篇基于 Svelte 官方文档中的 FAQ 页面，系统梳理了 Svelte 用户最常问到的问题：新手入门路径、官方支持渠道、编辑器格式化与文档化方案、测试策略（单元测试 / 组件测试 / E2E 三层体系）、路由与移动端方案，以及最容易被误解的“未使用 CSS 为何会被移除”这一编译行为。文中每一项结论都回溯到了当前仓库中的源码与测试实现，例如 CSS 选择器裁剪分析器 css-prune.js 与未使用选择器警告 css-warn.js，读完你可以既掌握 FAQ 的官方答案，又理解其背后的编译器原理，并能直接按仓库内路径复现验证。

新手入门与支持渠道

FAQ 的第一个问题就是“我是 Svelte 新手，该从哪里开始”。官方建议是：

• 通过交互式教程入门——教程每一步聚焦一个具体知识点，可以直接在浏览器中编辑并运行真实的 Svelte 组件；
• 时间预期很明确：5 到 10 分钟即可上手，约一个半小时可以完成整个教程。

关于提问与支持，官方给出的优先级是：

1. 语法问题：先查参考文档（本仓库中对应 documentation/docs/98-reference/ 目录下的完整参考，如 20-svelte.md）；
2. 具体报错、代码级问题：适合到 Stack Overflow 等问答社区，先搜已有标签问题，再提问；
3. 最佳实践、架构讨论：适合社区论坛与聊天频道（Discord、Reddit 的 Svelte 版块）。

工具链：格式化、高亮与组件文档

FAQ 对编辑器生态的回答可以浓缩成三点：

• 语法高亮：使用官方 VS Code 扩展 Svelte for VS Code（基于 Svelte Language Server）；
• 自动格式化：使用 Prettier 搭配 prettier-plugin-svelte 插件处理 .svelte 文件；
• 组件文档注释：在支持 Svelte Language Server 的编辑器中，可以用特殊格式化的注释为组件、函数和导出写文档。

文档中给出的完整示例展示了两种注释形态：

<script>
	/** What should we call the user? */
	export let name = 'world';
</script>

<!--
@component
Here's some documentation for this component.
It will show up on hover.

- You can use markdown here.
- You can also use code blocks here.
- Usage:
  ```svelte
  <main name="Arethra">
  ```
-->
<main>
	<h1>
		Hello, {name}
	</h1>
</main>

要点有两处：其一是 export let name 上方的 JSDoc 式注释会在悬停时展示（注意这是 legacy 写法，当前版本推荐 runes 模式下的 $props，见 [05-$props.md](https://gitcode.com/GitHub_Trending/sv/svelte/blob/b2c22ab66d0978dfa14bb92196a6ab45ad0031a4/documentation/docs/02-runes/05-$props.md?utm_source=gitcode_repo_files)）；其二是描述整个组件的 HTML 注释必须以 @component 开头，这是 Language Server 识别组件级文档的约定标记，注释内支持 Markdown 和代码块。

测试策略：单元测试、组件测试与 E2E 三层体系

FAQ 中“如何测试 Svelte 应用”一节给出的核心观点是：应用的结构决定了测试方式。并非所有逻辑都应放在组件里——数据转换、跨组件状态管理、日志等都可以（也更适合）抽到组件之外。同时强调：Svelte 库自身拥有完整测试套件，你无需编写测试去验证 Svelte 内部实现细节。

一个 Svelte 应用通常有三类测试：

单元测试（Unit Tests）

聚焦业务逻辑的孤立验证，通常是单个函数和边界条件。把尽量多的逻辑从组件中抽离出来，可以让更大范围的应用代码被单元测试覆盖，且测试保持精简、快速。使用 SvelteKit 创建项目时会被询问是否配置 Vitest 用于单元测试，当然也可以使用其他测试运行器。

仓库内的 02-testing.md 进一步给出了手动配置 Vitest 的完整步骤：安装 vitest 后在 vite.config.js 中通过 resolve.conditions: ['browser'] 告诉 Vitest 在 Node 环境下也使用 package.json 的 browser 入口。这一点在当前仓库中可直接印证——根目录的 vitest.config.js 就是 Svelte 自身的测试配置，测试代码还会导入 svelte 的运行时入口（如 packages/svelte/src/internal/client/index.js）。

组件测试（Component Tests）

验证组件挂载后在整个生命周期中的行为，需要一个提供 DOM 的环境。由于 Svelte 是编译器而非普通运行时库，组件必须先被编译再挂载，然后才能断言元素结构、事件监听器、状态等。工具谱系从内存实现（jsdom + Vitest）到真实浏览器方案（Playwright、Cypress 的组件测试模式）不等。

这一“编译即测试”的特性在仓库结构中有直接体现：packages/svelte/tests/ 目录下的测试按维度组织——runtime-runes/ 验证 runes 响应式行为、runtime-browser/ 在真实浏览器中运行（配套 driver.js 驱动）、hydration/ 验证 SSR 产物的水合、compiler-errors/ 验证编译期报错。测试统一由 suite.ts 提供的测试基座驱动。

端到端测试（End-to-End）

为了确认用户能真实地与完整应用交互，需要以尽可能接近生产的方式加载并操作部署后的应用。SvelteKit 项目创建时会询问是否配置 Playwright 用于 E2E 测试。

路由：SvelteKit 是官方答案

FAQ 对“有没有路由器”的回答是：官方路由库是 SvelteKit——它把文件系统路由、SSR 与 HMR 集成在一个易用的包里，定位类似 React 生态的 Next.js、Vue 生态的 Nuxt.js，并且支持基于 hash 的路由以适配纯客户端应用。当然你也可以用任何第三方路由器。这与当前仓库的定位一致：本仓库是 Svelte 编译器与运行时本身，路由能力由 SvelteKit 生态包提供。

移动端：SvelteKit SPA 加 Tauri / Capacitor

FAQ 承认大多数原生移动端应用并不使用 JavaScript，但如果你希望复用现有 Svelte 组件与知识，有两条路：

1. 将 SvelteKit SPA 打包为移动应用，使用 Tauri 或 Capacitor，摄像头、定位、推送等移动端能力可通过两者各自的插件体系获得；
2. 使用 Symbiote Native（构建在 React Native 基础设施之上）将 Svelte 编译为原生组件。

值得注意的进展是：Svelte 5 的自定义渲染器（custom renderer）支持已在推进中但尚未合并，该 API 落地后将支持 Lynx JS、Svelte Native 等框架，Symbiote Native 也会采用它。FAQ 同时澄清了一个常见误区：Svelte 4 时代可选的 Svelte Native 在 Svelte 5 中目前不受支持。

核心原理解析：Svelte 为什么必须移除未使用的样式

FAQ 中最具技术深度的一条是：“能否让 Svelte 不移除我的未使用样式？”官方答案干脆：不能（No）。移除并警告正是为了防止后续问题。这段回答解释了组件样式作用域的完整机制，值得逐层展开。

作用域机制：编译器生成的唯一类名

Svelte 的组件样式作用域是这样实现的：编译器为每个组件生成一个该组件独有的 class，把这个 class 添加到组件中所有受 Svelte 管控的相关元素上，再把它附加到该组件样式的每个选择器上。最终 CSS 形如 .p { ... } 中的 p.svelte-hash 这类带散列后缀的选择器（散列可通过 customCssHash 选项定制，见测试样例 custom-css-hash）。

为什么“保留未使用选择器”没有好选项

当编译器无法确定某个选择器会命中哪些元素时（典型场景：样式目标是子组件创建的节点或 {@html ...} 注入的节点），保留它只有两种坏结局：

• 保留选择器并加上作用域类：选择器大概率匹配不到预期元素——如果目标元素由子组件或 {@html} 创建，它不会带父组件的作用域类，必定失配；
• 保留选择器但不加作用域类：该样式就变成了全局样式，影响整个页面。

两种结局都不可接受，所以编译器选择直接移除该规则并发出 css_unused_selector 警告。

源码印证：裁剪分析与警告链路

从源码结构看，这套行为由分析阶段的 CSS 子管线实现：

• css-prune.js 负责“选择器是否真的会命中组件内节点”的分析，内部用 NODE_PROBABLY_EXISTS / NODE_DEFINITELY_EXISTS 两级存在性状态和正向/反向遍历（FORWARD / BACKWARD）沿 DOM 树匹配选择器。该文件还维护了两份白名单：details/dialog 的 open 属性选择器白名单（因为 open 可能被运行时切换），以及 HTML 规范中大小写不敏感的枚举属性集合（如 type、role），保证属性选择器分析符合浏览器真实匹配行为；
• css-warn.js 的 warn_unused 遍历样式表，对 metadata.used 为假的选择器调用 w.css_unused_selector 发出警告（并特意跳过 :is()/:where() 内部以免重复标记）；
• 警告文案定义于 warnings.js 的 css_unused_selector：Unused CSS selector "..."。

行为有大量回归测试保障，例如 unused-selector、unused-selector-ternary（三元表达式导致编译器无法确定分支）、unused-selector-string-concat 等样例，可以逐一对照选择器被裁剪的边界条件。

正确做法：显式使用 :global(...)

FAQ 给出的出口是：如果你确实要样式化一个 Svelte 在编译期无法识别的目标，就显式使用 :global(...) 选择全局样式。而且 :global(...) 可以只包裹选择器的一部分——.foo :global(.bar) { ... } 会样式化组件 .foo 元素内部出现的任意 .bar 元素。只要选择器起点是当前组件中的某个父元素，这种“部分全局”的选择器几乎总能达到目的。

本仓库的 02-global-styles.md 给出了完整的三种形态：

<style>
	:global(body) {
		/* applies to <body> */
		margin: 0;
	}

	div :global(strong) {
		/* applies to all <strong> elements, in any component,
		   that are inside <div> elements belonging
		   to this component */
		color: goldenrod;
	}

	p:global(.big.red) {
		/* applies to all <p> elements belonging to this component
		   with `class="big red"`, even if it is applied
		   programmatically (for example by a library) */
	}
</style>

另有整组全局的 :global { ... } 块写法，以及全局 @keyframes 需以 -global- 前缀命名的约定（编译时会去掉前缀，别处直接引用原动画名）。

其他 FAQ 结论速览

• Svelte 能扩展吗（Does Svelte scale?）：官方表示相关博客文章会补上，目前指向社区讨论的 issue #2546，仓库中无现成结论，不作引申；
• 有没有 UI 组件库：有多个组件库及独立组件（由社区维护的 packages 清单收录）；
• Svelte v2 还在维护吗：不再添加新特性，只有极严重或安全类 bug 才可能修复，v2 文档仍独立保留；
• 如何做 HMR：推荐 SvelteKit（基于 Vite，开箱支持 HMR，构建在 svelte-hmr 之上）；rollup 与 webpack 也有社区热更新插件（rollup-plugin-svelte-hot、svelte-loader）。

小结

这份 FAQ 的价值在于给出了“官方立场”：未使用 CSS 的移除不是可关闭的开关，而是组件样式作用域模型的正确推论——要么作用域失配，要么泄漏为全局样式，唯一干净的做法是用 :global(...) 显式声明意图；测试上则以“把可测逻辑移出组件 + 三层测试分工”为原则。以上每一条都可以用本仓库的证据复核：CSS 裁剪逻辑在 packages/svelte/src/compiler/phases/2-analyze/css/，测试策略在 packages/svelte/tests/ 有活生生的大规模示范，全局样式语法细节在 documentation/docs/04-styling/ 有完整参考。