在使用 VSCode 进行开发时，一个常见的困扰是拼写检查插件会在自定义的变量名或 API 名称上标记红色波浪线。例如，当你输入“ReactQuery”或“ZodSchema”这类专有名词时，编辑器却提示“拼写错误”。

这通常是因为 Code Spell Checker 扩展默认仅识别标准英文词汇。项目中的特定库名、技术缩写或内部术语，对它而言都是未知词汇。要让编辑器停止对这些词汇的警告，你需要主动配置忽略规则。

解决方案有多种，你可以根据需求选择：从全局性的项目配置，到灵活的单行控制，再到使用正则表达式进行批量模式过滤，总有一种方法适合你的工作流。

在项目级配置中添加 words 字段

如果你的项目中存在大量重复出现的自定义术语——例如团队内部约定的 API 名称、特定的第三方库标识，或者一系列自定义的 Hook 名称——最清晰高效的方式是将它们统一添加到项目根目录的 .cspell.json 配置文件中。

这种做法的优势在于，配置仅对当前项目生效，比修改全局设置更加精准，同时也便于通过版本控制系统（如 Git）进行团队协作和配置共享。

• 首先，进入你的项目根目录，找到或新建一个名为 .cspell.json 的文件。
• 确保文件中包含一个名为 "words" 的数组，并将所有需要忽略的词汇添加进去。参考格式如下：

{  "words": ["ReactQuery", "ZodSchema", "JWT", "APIKey"]}

• 保存文件后，这些词汇在当前项目的所有文件中都将不再触发拼写警告。

使用 // cSpell:ignore 进行行内临时忽略

并非所有情况都适合修改项目配置。例如，某行代码中可能包含动态生成的路径、临时占位符，或者一些仅出现一次的怪异字符串片段。为它们去更新全局配置显得不够灵活。

此时，行内注释指令便是一个完美的解决方案。

• 你只需在目标代码行的末尾，添加一条特殊注释：// cSpell:ignore myCustomId, apiV2, userId。
• 该指令支持使用空格或逗号分隔多个词汇，并且区分大小写。
• 最关键的是，这个忽略指令仅对当前所在行有效，不会影响文件中的其他代码，提供了极高的灵活性。

通过 cSpell.ignoreRegExpList 批量过滤特定模式

当你需要忽略的是一整类具有固定模式的“干扰项”时，例如全大写的缩写（如 HTTP、UI），或者带有下划线的环境变量（如 NODE_ENV、API_VERSION），逐个添加到单词列表会非常繁琐。

面对这类需求，正则表达式是最强大的工具。

• 你可以在 VSCode 的 settings.json（用户或工作区设置）中，或者在项目的 .cspell.json 配置文件里，添加一个名为 "cSpell.ignoreRegExpList" 的数组。
• 例如，添加以下两条规则：

"cSpell.ignoreRegExpList": ["\b[A-Z]{2,}\b", "\b[A-Z]+_[A-Z_]+\b"]

• 第一个正则表达式 \b[A-Z]{2,}\b 会匹配并忽略所有由两个及以上大写字母组成的单词（例如“HTTP”、“UIKIT”）。
• 第二个正则表达式 \b[A-Z]+_[A-Z_]+\b 则专门用于处理像“NODE_ENV”、“API_VERSION”这类使用下划线连接的大写变量名。
• 请注意，在 JSON 文件中书写正则表达式时，反斜杠需要进行转义，因此你会看到双反斜杠。此外，这些正则表达式通常不支持跨行匹配。

一个常见的配置误区

最后，有一个细节问题经常导致开发者困惑：明明已经在 .cspell.json 中添加了词汇，为什么 VSCode 仍然标记为错误？

问题可能源于以下两点：

1. 配置文件位置错误：.cspell.json 文件必须放置在项目的根目录，或者被 VSCode 识别为工作区文件夹的根目录下。如果你将其放在了 src/ 这样的子目录中，插件很可能无法读取到该配置。

2. 文件语言未被包含在检查范围内：Code Spell Checker 默认只对一部分编程语言文件启用拼写检查。如果你正在编辑的文件类型（例如某种自定义后缀的文件）不在 cSpell.enabledLanguageIds 这个设置列表中，那么拼写检查功能根本不会激活，你的忽略词列表自然也就不会生效。

因此，当配置似乎没有起作用时，不必急于排查复杂原因。首先检查配置文件的位置和当前文件的语言设置，往往就能快速定位并解决问题。