企业官网建设流程全解析

• 文档
• 教程

本指南基于本仓库 TypeScript News 新闻栏目（含 捷克语版）编写，介绍 TypeScript 7 原生语言服务新增的workspaceSymbols.scope偏好设置：在多项目工作区中，如何把"工作区符号搜索"（即编辑器里按符号名全局跳转、如Go to Symbol in Workspace）的结果集从"所有已打开项目"收敛到"当前项目"。读完本文，你将理解该设置的两个取值及其语义、VS Code 原生扩展如何配合传递上下文文档，以及为何这一变更被设计为显式开启（opt-in）的行为。

背景：TypeScript 7 的原生语言服务与 LSP

要理解这项变更，先要回到 TypeScript 7.0。据本仓库新闻栏目记载（TypeScript 7.0 已发布），TypeScript 7 是首个基于 Go 编写的原生编译器与语言服务的稳定版本，并且把语言服务迁移到了Language Server Protocol（LSP）之上——支持 LSP 的编辑器可以共享同一个原生底座，获得更快的项目加载、诊断、补全与导航能力。

工作区符号搜索正是 LSP 提供的一项经典导航能力：客户端（编辑器）向服务端发送workspace/symbol请求，按名称在工作区范围内查找类、函数、变量等符号。当 VS Code 中同时打开多个 TypeScript/JavaScript 项目时，该请求默认会跨越"所有已打开项目"检索，这是旧行为，也是本次变更想要提供收敛选项的原因。

核心变更：workspaceSymbols.scope偏好设置

Microsoft 已将"工作区符号搜索范围"合入 TypeScript 原生语言服务。新增的语言服务偏好（preference）workspaceSymbols.scope有两个取值：

关键语义在于第二行的"传入文档"：语言服务需要知道当前上下文是哪个文件，才能据此判断"当前项目"到底是哪一个。这正是原生 VS Code 扩展配合改动的地方。

VS Code 原生扩展如何配合：向workspace/symbol请求注入文档

原文明确指出，原生 VS Code 扩展现在会在每次workspace/symbol请求中附加一个受支持的 TypeScript 或 JavaScript 文档：

1. 优先使用当前活动（active）文档——即光标所在、正在编辑的.ts/.js文件；
2. 若没有活动文档，则回退到某个已打开的受支持文档。

语言服务只有在workspaceSymbols.scope为currentProject时才使用这个附加文档来限定搜索范围；否则继续执行跨所有已打开项目的旧式搜索。换句话说：

• 客户端侧（VS Code 扩展）：总是携带文档上下文（成本很低，是纯附加信息）；
• 服务端侧（原生语言服务）：是否利用该上下文，完全由workspaceSymbols.scope决定。

这种"客户端无条件上报、服务端按偏好消费"的设计，让旧行为在默认状态下保持不变，也避免了为每个客户端单独做兼容分支。

为什么重要：多项目工作区中的同名符号歧义

在真实开发中，一个 VS Code 工作区往往同时挂着多个项目（例如 monorepo 中的多个子包、或同时打开的前后端仓库）。这些项目里经常出现相似命名的符号：比如多个包都导出createClient、config、useStore之类的通用名称。

默认的allOpenProjects会把所有项目中的同名符号混在一个结果列表里，开发者必须靠路径前缀手工分辨该进哪个文件。而切到currentProject后：

• 结果集被收敛到包含当前编辑文件的那个项目；
• 同名符号的歧义大幅减少，跳转命中率更高、心智负担更低。

由于默认值保留了既有行为，这一改进需要显式开启才生效——对不想改变习惯的用户零侵入。

实操：如何在多项目工作区启用与验证

workspaceSymbols.scope是语言服务的偏好设置，通过编辑器的设置机制下发（VS Code 中对应"偏好/设置"层；具体设置键名以你所安装的 TypeScript 7 原生 VS Code 扩展提供的设置说明为准，但语义与取值如下）：

1. 将workspaceSymbols.scope设置为currentProject，并确保使用 TypeScript 7 及之后的原生语言服务/原生 VS Code 扩展；
2. 打开至少两个包含同名符号的 TypeScript 或 JavaScript 项目；
3. 在一个项目的文件中触发工作区符号搜索（按符号名全局查找，对应 LSP 的workspace/symbol）；
4. 对比切换前后（allOpenProjects→currentProject）的结果集：切换后结果应仅来自包含当前编辑文档的项目。

判断依据：currentProject限定的是"包含传入文档的项目"，因此验证时务必让活动文档位于你希望限定搜索的那个项目中——扩展会优先采用活动文档作为上下文。

可用性与注意事项

• 合并时机：该变更在 TypeScript 7.0 之后才合入原生代码库，因此并非 7.0 自带的能力；
• 版本确认：官方来源未指明包含该设置的具体稳定 npm 版本，在依赖该设置之前，请先查看你已安装 TypeScript 版本的发布说明（release notes）确认其是否包含此特性；
• 不影响默认用户：未显式配置时，allOpenProjects行为与以往完全一致。

相关阅读

• 本主题英文原文：typescript-7-workspace-symbol-search-scope.md
• 本主题捷克语版本：cs-cz 版原文
• 新闻列表索引：TypeScript News 索引（英文） 与 捷克语版索引
• 同一批次的原生语言服务改进：TypeScript 7 改进 Go to Implementation 内存占用、TypeScript 7 在文件变更后刷新配置诊断
• 背景铺垫：TypeScript 7.0 发布公告

• 文档
• 教程