webstorm 不读取 .gitignore，必须通过 settings → editor → file types → ignored files and folders 添加 node_modules（不带斜杠）并执行 invalidate caches and restart 才能彻底忽略索引。
WebStorm 不会自动读取 .gitignore，配置它只影响 Git，对 IDE 索引、跳转、补全完全无效。想让 WebStorm “看不见” node_modules 或其他目录，必须单独配 Ignored Files and Folders。
为什么 .gitignore 里写了 node_modules/ 却还是卡
这是最常被误解的一点：.gitignore 只告诉 Git 别跟踪这些文件，WebStorm 根本不看它。IDE 自己维护一套索引系统，node_modules 一旦被扫描，就会触发数万文件解析——表现为“Loading indexes”卡死、CPU 暴涨、Ctrl+Click 还能跳进 node_modules 里的包、Find Usages 慢得离谱。
常见错误操作包括：
- 只在
.gitignore加了node_modules/，以为万事大吉 - 右键
node_modules→ Mark Directory as → Excluded，但没删.idea缓存就重启 - 用 pnpm/yarn link 后还硬标 Excluded，结果模块解析失败，报
Cannot find module
全局忽略 node_modules 的唯一可靠路径
这不是“推荐做法”，而是 WebStorm 官方文档和 2026 年实测中唯一稳定生效的方式。它绕过项目级配置污染，不破坏符号链接，也不干扰 TypeScript 类型解析。
操作步骤（2022.3+ 版本通用）：
- 打开
File > Settings > Editor > File Types > Ignored Files and Folders - 在输入框末尾添加：
node_modules（注意：不带斜杠、不加星号、不写路径） - 点击
Apply，然后必须执行File > Invalidate Caches and Restart > Invalidate and Restart
验证是否成功：
- 重启后，Project 面板中
node_modules显示为灰色且不可展开 - 右键菜单里没有
Open in Terminal或Reveal in Finder - 按
Ctrl+Shift+N搜索任意文件，搜不到node_modules里的内容
Excluded 和 Ignored Files and Folders 的本质区别
这两个功能名字像，作用却完全不同，混用必出问题：
-
Mark as Excluded是项目级标记，写在.idea/{project}.iml里，会影响模块解析逻辑（尤其对@types、pnpm hard links） -
Ignored Files and Folders是 IDE 级过滤，仅控制索引行为，不修改项目结构，不影响 import 解析或类型检查 - Deployment 上传是第三套系统：即使
node_modules已 Ignored，若没在Tools > Deployment > Options > Exclude items by name里填node_modules/，它仍会被上传
所以如果你同时要：不索引 + 不上传 + 不误提交，得配三处：Ignored Files and Folders、Deployment exclude、.gitignore——它们互不替代。
怎么忽略单个文件或子目录（比如 node_modules/my-local-pkg）
WebStorm 不支持右键单个文件点 Excluded，这是硬限制。但你可以用 Ignored Files and Folders 实现类似效果：
- 支持精确路径：直接加
node_modules/my-local-pkg（不带斜杠） - 支持通配符：比如
*.log、dist/**（注意双星号需 WebStorm 2024.1+） - 不支持正则，也不识别
.gitignore语法（如!dist/public白名单无效）
如果误加了不该忽略的路径，删掉后同样要 Invalidate Caches and Restart 才能恢复索引——缓存不会自动更新。
真正麻烦的从来不是“怎么加”，而是加完之后 IDE 还在偷偷索引。所有失效现象，90% 都是因为漏了 Invalidate Caches 这一步，或者把 node_modules/ 错写成 node_modules/（带斜杠）导致匹配失败。
