企业官网建设流程全解析

• 编程语言
• 编译器
• 开发工具

自动导入（Auto Import）是 TypeScript 语言服务最核心的编辑体验之一：当你在代码中敲下一个尚未导入的标识符前缀时，编辑器会推荐来自其他模块的导出，并在你接受补全的同时自动把对应的import语句写入文件。本文以当前仓库（Go 实现的 TypeScript 语言服务）中的基线测试 autoImportCompletion3.baseline.md 为线索，完整拆解该测试的输入输出、驱动它的测试用例，以及背后的补全与偏好配置实现，帮助你理解“敲前缀 → 补全候选 → 自动插入 import”这条完整链路。

基线文件解读：一次自动导入补全的完整快照

基线测试文件（baseline）是测试框架在运行后生成的“预期输出快照”。文件本身分为两段：上半段是测试输入（=== Auto Imports ===标记下的源码片段），下半段是语言服务对输入执行自动导入补全后返回的结果。关联文档 autoImportCompletion3.baseline.md 的全部内容如下：

// === Auto Imports === // @FileName: /c.ts import { aa, someVar } from "./a.ts"; someVar; b/**/

import { aa, bb, someVar } from "./a.ts"; someVar; b

输入片段中的/**/是 fourslash 测试约定中的光标标记（marker），表示补全请求发生的位置。整段输入的含义是：

1. 当前编辑的文件是c.ts；
2. 文件顶部已经存在一条部分导入语句import { aa, someVar } from "./a.ts";；
3. 文件正文中使用了someVar（说明该模块的导入已在使用中）；
4. 用户正在输入b，光标停在b之后，等待补全。

输出片段则展示了“接受补全后”文件应变成的样子：bb被加入到了既有的 import 花括号列表中，并且光标处的b被替换为完整的标识符bb，其余代码原样保留：

import { aa, bb, someVar } from "./a.ts"; someVar; b

这个基线最值得注意的细节是：补全没有新生成一条import { bb } from "./a.ts";，而是把bb合并进了同模块既有 import 语句——这正是自动导入补全在真实编辑器中的典型行为，也是本测试要验证的核心场景。

驱动测试用例：TestAutoImportCompletion3

基线文件本身是“结果快照”，真正定义输入与断言逻辑的是对应的测试用例 autoImportCompletion_test.go 中的TestAutoImportCompletion3。该用例通过 fourslash 测试框架构造了一个三文件虚拟工程：

const content = `// @Filename: a.ts export const aa = "asdf"; export const someVar = 10; export const bb = 10; // @Filename: c.ts import { aa, someVar } from "./a.ts"; someVar; b/**/ `

a.ts中导出三个符号，其中aa与someVar已在c.ts中导入，bb尚未导入；c.ts中光标位于b/**/。随后用例调用补全验证，并声明预期结果：

f.VerifyCompletions(t, "", &fourslash.CompletionsExpectedList{ UserPreferences: &lsutil.UserPreferences{ IncludeCompletionsForModuleExports: core.TSTrue, IncludeCompletionsForImportStatements: core.TSTrue, }, IsIncomplete: false, ItemDefaults: &fourslash.CompletionsExpectedItemDefaults{ CommitCharacters: &DefaultCommitCharacters, EditRange: Ignored, }, Items: &fourslash.CompletionsExpectedItems{ Includes: []fourslash.CompletionsExpectedItem{"bb"}, }, }) f.BaselineAutoImportsCompletions(t, []string{""})

从中可以提炼出三个关键断言：

• 候选集合：在b前缀下，补全列表必须包含bb（Includes），表明模块导出已被纳入补全；
• 偏好开关：用例显式开启IncludeCompletionsForModuleExports与IncludeCompletionsForImportStatements两个偏好，说明自动导入补全依赖这两项用户偏好；
• 基线录制：BaselineAutoImportsCompletions负责把“应用补全后的文件内容”输出为上文看到的基线文档，用于后续回归比对。

同文件中的TestAutoImportCompletion1、TestAutoImportCompletion2与之构成互补：前者验证“存在多个可导入模块时自动导入仍生效”，并额外验证关闭偏好后anotherVar不再出现在候选里；后者验证“同一模块内多个未导入导出”的候选收集。三者共同覆盖了自动导入补全的常见路径。

底层原理：自动导入补全的完整调用链

基线测试的行为由语言服务补全模块与自动导入注册表共同实现，关键代码分布在三个位置。

用户偏好：自动导入的两个总开关

自动导入补全是否开启，由 userpreferences.go 中定义的两个偏好控制，二者默认均为TSTrue（开启）：

IncludeCompletionsForModuleExports: core.TSTrue, IncludeCompletionsForImportStatements: core.TSTrue,

对应的原始配置键与编辑器配置映射如下（该文件中的raw/config标签）：

用户若在编辑器设置中关闭suggest.autoImports，模块导出将不再出现在补全列表——这正是TestAutoImportCompletion1后半段（将两偏好置为TSFalse后断言排除anotherVar）所验证的行为。偏好类型为core.Tristate（TSTrue/TSFalse/TSUnknown），与 TypeScript 原生实现的三态偏好保持一致。

补全入口：候选的过滤与导入改写

补全请求进入 completions.go 后，自动导入逻辑在多个环节生效，例如：

• 当IncludeCompletionsForImportStatements开启时，为补全项附加可供编辑器执行的导入改写（import statement completion info）；
• 当IncludeCompletionsForModuleExports关闭时，模块导出候选会被过滤掉。

在b/**/这个场景里，bb之所以能进入候选，是因为它来自a.ts的导出，且当前文件尚未导入它；补全接受后，语言服务计算出最小改动：在既有import { aa, someVar }的花括号中插入bb并保持排序，同时把b替换为bb，最终得到基线中的结果。

导出索引：自动导入注册表

候选“从哪来”的问题由 autoimport/registry.go 负责。该注册表维护着项目中所有可导入模块的导出符号索引，并在补全时按当前文件所在模块、已导入符号等条件筛选。它还内置了一份“已知递归搜索包”名单（如lodash、react、next等），对这些特殊包采用递归搜索策略以提升候选召回率。测试文件 registry_test.go 中同样以IncludeCompletionsForModuleExports/IncludeCompletionsForImportStatements偏好驱动注册表行为验证，与 fourslash 测试互为印证。

fourslash 测试框架：输入如何被解析

基线中的// @Filename:指令与/**/光标标记由 fourslash.go 解析：@Filename声明文件归属，/**/定位补全请求发生位置。测试运行时，框架按指令在虚拟文件系统上创建文件、定位光标、发起补全请求，再将结果与断言比对、输出基线。

配置与实测：如何在自己的项目里复现该行为

要在真实 TypeScript 工程中复现本测试描述的行为，只需三步：

1. 准备两个文件：

   // a.ts export const aa = "asdf"; export const someVar = 10; export const bb = 10;

   // c.ts import { aa, someVar } from "./a.ts"; someVar; b; // 在这里触发补全

2. 在c.ts中把光标移到b后，呼出补全（编辑器内通常为 Ctrl+Space 或直接键入字符）；
3. 接受bb候选，观察 import 语句被就地更新为import { aa, bb, someVar } from "./a.ts";。

若补全列表中看不到模块导出，请检查编辑器设置：确认suggest.autoImports（对应includeCompletionsForModuleExports）与suggest.includeCompletionsForImportStatements均处于开启状态。注意，自动导入补全仅对“尚未导入的导出符号”生效；已在 import 中的符号（如本例的aa、someVar）不会重复推荐。

扩展阅读：自动导入测试家族

自动导入在仓库测试中覆盖面很广，围绕本基线可继续查看：

• 基线快照目录 fourslash/autoImports：包含autoImportCompletion1/2/3、autoImportCrossProject*、autoImportFileExcludePatterns*、importModuleSpecifierPreference*等数十个基线，分别覆盖跨项目导入、文件排除模式、模块说明符偏好等场景；
• 测试用例目录 fourslash/tests：autoImportCompletion_test.go、autoImportCrossProject_paths_toSrc_test.go、autoImportFileExcludePatterns_test.go等对应上述基线；
• 实现源码：补全逻辑 completions.go、偏好定义 userpreferences.go、导出注册表 registry.go。

其中autoImportCompletion1.baseline.md与autoImportCompletion2.baseline.md与本基线最相近，分别演示“多模块可导入”与“同模块多导出”场景，可作为对比样本进一步理解自动导入补全的候选来源与合并规则。

小结

autoImportCompletion3.baseline.md虽然只有十余行，却完整记录了自动导入补全中最常见、也最关键的一种行为：在既有 import 语句上就地合并新符号，而不是新开一条 import。通过对照测试用例 autoImportCompletion_test.go、补全实现 completions.go 与偏好定义 userpreferences.go，可以清晰还原这一能力的触发条件（两个偏好开关）、候选来源（模块导出注册表）与结果形态（import 合并改写），从而在阅读语言服务代码或调试编辑器自动导入行为时做到心中有数。

• 编程语言
• 编译器
• 开发工具