Code Spell Checker插件默认不检查未在cSpell.enabledLanguageIds中明确列出的语言模式,如typescriptreact、vue等;需手动配置语言ID、启用复合词支持、使用patterns精准过滤而非ignoreWords,并在CI中改用cspell CLI而非插件。

有没有遇到过这种情况?明明安装了拼写检查插件,但在注释里写错了单词,却没有任何红色波浪线提示。这通常不是插件本身出了问题,而是它的默认配置没有覆盖到你正在使用的文件类型或语言。说白了,Code Spell Checker 这个工具,你得主动告诉它:“在哪些文件里查、具体查什么内容、以及哪些内容可以忽略”。
为什么 .ts 文件里的字符串不检查?看 cSpell.enabledLanguageIds
插件并不会自动识别所有的编程语言模式。尤其是像 TypeScript React(typescriptreact)或者 Vue 单文件组件(vue)这类复合型语言,很容易被遗漏。它只会在你明确列出的语言 ID 列表里生效。
- 首先,打开命令面板(快捷键是
Ctrl+Shift+P),运行Preferences: Open Settings (JSON)。 - 接着,确认
cSpell.enabledLanguageIds这个配置项包含了所有你需要的语言,比如:["ja vascript", "typescript", "typescriptreact", "ja vascriptreact", "vue", "markdown"]。 - 如果你还在使用 Astro 或 Svelte 这类框架,记得把
astro或svelte也加进去;否则,这些文件里标签内的字符串就会被直接跳过检查。 - 这里有个常见的误区:有人图省事,直接配置成
"*"通配符。这看似一劳永逸,但副作用很大,它会把.json或.yml配置文件里的字段名(例如user_id)全部标红,反而造成了更大的干扰。
中文注释总被标红?cSpell.language 和 cSpell.allowCompoundWords 得配齐
仅仅设置语言为 "zh" 是不够的。像“用户名”、“登录页”这类复合词,很容易被错误地拆分成单字或者被错误切分,从而触发误报。必须配合启用复合词支持,才能让插件正确识别它们。
cSpell.language这个配置项,推荐使用["en", "zh-CN"](注意是zh-CN而非简单的zh),它对简体中文的词干识别会更加稳定。- 必须同时加上
cSpell.allowCompoundWords: true这个设置。否则,像useStore、httpStatus这类驼峰命名的变量或函数名,会被当作拼写错误。 - 遇到不认识的专有名词,别急着点右键选择“Add to user dictionary”——这会把该词添加到你的全局用户词典,污染所有项目。更好的做法是选择“Add to workspace dictionary”,它会自动将这个词写入当前项目的
.cspell.json文件中,作用范围仅限于当前项目。 - 如果因为使用拼音输入法而残留了拼音片段(比如
zhang、li),可以临时关闭英文词典,只启用中文词典:cSpell.dictionaries: ["chinese"]。
误报太多?用 .cspell.json 的 patterns 精准过滤,别瞎加 ignoreWords
直接使用 ignoreWords 列表是一种全局放行策略,很容易把真正的拼写错误也一并放过。而使用正则表达式定义的 patterns 则能实现按上下文精准过滤,比如只跳过 URL 链接、环境变量名或者文件路径片段。
- 在项目的根目录下创建一个名为
.cspell.json的配置文件,内容至少应包含以下结构:{ "version": "0.2", "language": "en", "words": ["vite", "zod", "prisma"], "patterns": [ {"name": "env-vars", "pattern": "\b[A-Z_]{3,}\b"}, {"name": "urls", "pattern": "https?://[\w./?=-]+"} ], "ignoreRegExpList": ["env-vars", "urls"] } - 这里的正则
\b[A-Z_]{3,}\b可以匹配像NODE_ENV、API_URL这样的环境变量,但会放过像i18n这样包含小写字母的单词。 - 需要注意:正则匹配的是整个 token(词元),而不是其中的子字符串。例如,
process.env.NODE_ENV这整段内容会被当作一个整体跳过,而不是只忽略最后那三个大写字母部分。 - 使用
ignorePaths来忽略整个目录时,必须写对 glob 模式:"node_modules/**"是有效的,而"node_modules/*"则无法匹配子目录。
CI/CD 里拼写检查失败?别指望插件,用 cspell CLI
VS Code 插件运行在图形界面的进程里,而 CI/CD 环境通常没有语言服务上下文,也没有激活的编辑器实例,插件根本启动不了。因此,在持续集成流程中,必须使用命令行工具。
- 在本地验证拼写检查命令是否有效:
npx cspell --no-progress "**/*.{js,ts,md,txt}" - 在 CI 配置中(以 GitHub Actions 为例)可以这样写:
run: npx cspell@6 --config .cspell.json --no-progress "**/*.{js,ts,md}" - 务必确保 CI 环境中使用的
.cspell.json配置文件与本地开发环境保持一致。插件会读取工作区配置,而 CLI 工具默认只读取项目根目录下的.cspell.json,不会合并用户级别的全局设置。 - 不要在 CI 命令中过度使用
--quiet或--no-progress等静默选项——否则当检查出错时,你连错误发生在哪一行都看不到。
最后分享一个最容易被忽略的排查技巧:如果插件状态栏的图标根本没有出现,那么90%的可能性是 cSpell.enabledLanguageIds 配置没有匹配对,或者当前文件的“语言模式”被意外设置成了 plaintext。这时,只需点击编辑器右下角的语言标识,手动切换回正确的文件类型(如 TypeScript、Vue),效果比重装插件要快上十倍。
