.cspell.json必须放在项目根目录才生效，且需检查languageid是否在cspell.enabledlanguageids中；项目级words优先于用户级，应放私有词；行内注释和正则可临时或批量忽略。
忽略词加了但还是标红？先确认.cspell.json是否被识别
插件不会自动扫描任意位置的 .cspell.json 文件——它只认项目根目录（即 VSCode 打开的文件夹最顶层）下的配置。如果你把 .cspell.json 放在 src/ 或 config/ 里，插件根本看不到，words 字段再全也没用。
另外，检查当前文件的语言 ID 是否在 cSpell.enabledLanguageIds 列表中。比如你在写 .astro 文件，但配置里没包含 "astro"，那即使词加对了，也不会触发检查逻辑，更别说忽略。
- 运行命令
Developer: Inspect Editor Tokens and Scopes（Cmd+Shift+P），看右下角显示的languageId是什么 - 在
settings.json中确认该 ID 出现在cSpell.enabledLanguageIds数组里，或设为["*"]先兜底 - 保存后重启 VSCode，或执行
Code Spell Checker: Reload Configuration命令
全局 vs 项目级 cSpell.words 怎么选
用户级 cSpell.words（写在 settings.json 里）适合跨项目复用的通用缩写，比如 "JWT"、"APIKey"、"HTTP"；但别往里塞项目私有词，否则换个项目打开就误报。
项目级 words（写在根目录 .cspell.json）才是主力：库名（"ZodSchema"）、自定义 Hook（"useAuth"）、内部 API 路径片段（"userV2"）都该放这儿。它优先级高于用户设置，且可提交到 Git，团队成员开箱即用。
- 项目级配置必须是
.cspell.json或cspell.json，名字错一个字母都不行 -
settings.json中的cSpell.words是数组，不是字符串；漏掉中括号或引号会静默失效 - 大小写敏感：
"ReactQuery"不等于"reactquery"，驼峰词照原样写
临时忽略某一行或某个字符串
不是所有词都值得进白名单。比如动态路径 `/api/v${version}/data` 里的 version，或者带占位符的注释 // cSpell:ignore user_id, api_token，用行内注释最干净。
// cSpell:ignore 必须写在**该行末尾**，不能换行，多个词用空格或逗号分隔；// cSpell:ignoreLine 整行跳过；// cSpell:ignoreStart 和 // cSpell:ignoreEnd 包裹多行块——这些都只对当前文件生效，不污染配置。
- 注释必须紧贴代码，前面不能有空行，否则插件可能解析失败
- 如果一行里有多个疑似错误词，但只想忽略其中几个，得列全：
// cSpell:ignore MyCustomId, userId - 注意不要和 ESLint 注释混用顺序，避免被其他插件误读
正则批量忽略缩写和环境变量
手动加几百个大写缩写（NODE_ENV、API_VERSION、UIKIT）太累，cSpell.ignoreRegExpList 是更可持续的方案。
它支持写在 settings.json 或 .cspell.json 里，值是字符串数组，每个元素是一个正则表达式。常用两个：
-
"\b[A-Z]{2,}\b"：跳过所有 ≥2 个连续大写字母组成的单词（HTTP、XML） -
"\b[A-Z]+_[A-Z_]+\b"：跳过全大写下划线命名（NODE_ENV、DB_HOST） - 正则必须用双反斜杠转义，单斜杠会报错；且不支持跨行匹配，别指望它处理换行字符串
真正容易被忽略的是：正则写完不测试。建议先在 VSCode 的「查找」面板（Cmd+F）里粘贴正则，手动验证是否命中目标词——错一条，整条规则就失效。
