插件不生效需确认三件事:右下角有Spell图标且插件已启用;文件语言模式正确(如JavaScript React);cSpell.language设为["en","zh"]并开启allowCompoundWords。

插件装了但没反应?先确认三件事
Code Spell Checker 装完不标红,90% 是“看似启用、实则静默”。它不会主动弹窗提醒你配置错了,只会安静地失效。
- 检查右下角状态栏:打开任意
.js或.md文件,看有没有出现「Spell」图标或语言标识(如en);没有就说明根本没激活 - 进扩展面板搜
Code Spell Checker,确认右下角显示「已启用」——不是「已安装」,是「已启用」 - 按
Ctrl+Shift+P(Win/Linux)或Cmd+Shift+P(Mac),输入Change Language Mode,确认当前文件语言是JavaScript React而不是JavaScript;Vue/TSX 模板字符串、JSX 中的文本全靠这个识别,错一个模式,整个字符串都不查
cSpell.language 配置不对,中文注释永远被无视
默认只开英文词典,"zh" 不是可选项,是必填项。而且 "zh" 和 "zh-cn" 效果不同:"zh" 匹配简体词干,"zh-cn" 才能更好识别“登录页”“用户名”这类复合词——但前提是同时开启 cSpell.allowCompoundWords: true,否则照样标红。
- 打开
settings.json,确保有这一行:"cSpell.language": ["en", "zh"] - 加一句:
"cSpell.allowCompoundWords": true,不然“useStore”“httpStatus”这种驼峰词会被拆成“use”“store”“http”“status”,全报错 - 别用
"cSpell.enabled": false全局关掉——很多人在排查时临时加了这句,后来忘了删,结果重启 VSCode 后一切照旧“不工作”
为什么变量名不标红?这是设计,不是 bug
Code Spell Checker 默认**不检查变量名、函数名、类名**,只查 注释、字符串字面量 和 Markdown 文本。这是有意为之:技术术语太多,硬查反而满屏波浪线。
- 想查变量名?可以,但得手动开:
"cSpell.checkProgrammaticTypes": true,不过强烈不建议——zustand、vitepress、tsconfig这类词会持续报错 - 真正该做的是:在项目根目录建
.cspell.json,把项目专属词加进words字段,比如:"words": ["zustand", "vitepress", "tsconfig"] - 别右键「添加到用户词典」——那会污染所有项目;优先选「Add to workspace dictionary」,它会自动写进当前项目的
.cspell.json
CI/CD 里拼写检查失败?别用插件,用 CLI
VSCode 插件是编辑器内运行的,CI 环境里没 GUI、没语言服务上下文,插件压根起不来。必须换命令行工具 cspell。
- 本地验证命令:
npx cspell --no-progress "**/*.{js,ts,md,txt}" - CI 脚本里要排除干扰路径:
--ignore="node_modules/**" --ignore="dist/**" --ignore="**/*.min.js" -
.cspell.json必须存在且合法,CLI 不读 VSCode 的settings.json;少一个逗号,整个 CI 就 exit code 1
最常被跳过的点:插件依赖语法高亮来区分字符串和代码,而语法高亮又依赖正确的 languageMode。改个文件后缀、切错语言模式、或者用了未注册的自定义语言,拼写检查就断连——它不报错,只是沉默。



















