WebStorm 忽略 dist 等文件夹不建索引

场景

每次执行打包都会生成一个 dist 文件夹，如果不设置忽略。 webstorm 都会对 dist 文件夹建索引，这是不需要的。

解决方法

设置如下

索引是什么，为什么要排除

WebStorm（以及所有 JetBrains IDE）的核心能力全部建立在索引之上。打开项目时它会把每个文件解析成 AST，把里面的符号、引用关系、字符串字面量都建成倒排索引存起来。这份索引是「跳转到定义」「查找所有用法」「重命名重构」「代码补全」能瞬间响应的原因——它不是每次都去扫文件，而是查表。

代价是建索引本身很贵。它要读文件、解析语法、写索引文件，CPU 和磁盘 IO 都吃得厉害。dist 这类目录的特点正好是「文件多、体积大、内容是机器生成的」，索引它有三重浪费：

建索引的时间和 CPU 白花了。打包产物动辄几十 MB 的 bundle，压缩过的 JS 一行几万个字符，解析这种文件的开销远高于正常源码。
搜索结果被污染。全局搜一个函数名，结果里一半是 dist 里的编译产物，得手动跳过。这是日常最烦人的一点。
每次打包都要重建。dist 的内容每次构建都变，IDE 检测到文件变化就重新索引一遍，于是「跑一次 build，IDE 卡十秒」。

具体怎么设置

有两种做法，效果和适用场景不同。

做法一：Mark Directory as Excluded（推荐）

在 Project 面板里右键 dist 目录 → Mark Directory as → Excluded。目录会变成橙色，表示排除但仍可见。

也可以在 Settings → Directories（老版本叫 Project Structure）里统一管理，这个页面能看到当前项目所有被标记的目录，批量调整更方便。

这种方式的配置存在 .idea/ 目录下的模块配置文件里（通常是 .idea/<项目名>.iml），内容大致是：

<content url="file://$MODULE_DIR$">
  <excludeFolder url="file://$MODULE_DIR$/dist" />
  <excludeFolder url="file://$MODULE_DIR$/node_modules" />
</content>

如果团队统一用 WebStorm，把 .idea/ 里这个文件提交进 git，所有人的排除配置就一致了。不过 .idea/ 目录里也有很多机器相关的内容（本地路径、个人偏好），全提交会引起冲突，一般的做法是在 .gitignore 里精细控制：

.idea/*
!.idea/modules.xml
!.idea/*.iml
!.idea/codeStyles/

做法二：Ignored Files and Folders

Settings → Editor → File Types → 最底下的 Ignored Files and Folders，往列表里加 dist;。

这是 IDE 全局的黑名单，对所有项目生效。但它比 Excluded 更狠——匹配上的目录在 Project 面板里完全消失，看不见也搜不到。想去 dist 里确认打包产物有没有正确生成时，会找不到入口，只能开终端或者 Finder。

所以这两者的取舍是：Excluded 是「不索引但可见」，Ignored 是「不索引且不可见」。对 dist 我用 Excluded，因为偶尔真的要去看产物；对 .tsbuildinfo、.turbo 这种纯缓存文件用 Ignored。

哪些目录该排除

按项目类型列一下常见的：

通用 — dist、build、out、coverage、.cache、tmp
Node — node_modules（下面单独说）
Next.js — .next
Nuxt — .nuxt、.output
Vite — node_modules/.vite
Vue CLI / webpack — dist
Turborepo / Nx — .turbo、.nx
Electron — release、dist_electron
Python 混合项目 — __pycache__、.venv、.pytest_cache

node_modules 是个特例，不要手动 Excluded。 WebStorm 对它有专门的处理：默认会把它标记成 Library 而不是普通源码目录，只索引类型定义和入口文件，不做全量解析。你手动 Exclude 掉之后，import 的类型推断、跳转到第三方库的定义、.d.ts 的补全都会失效，代价比省下的索引时间大得多。如果觉得 node_modules 拖慢了 IDE，正确的调整点是在 Settings → Languages & Frameworks → JavaScript → Libraries 里取消勾选不需要的库。

怎么确认设置生效了

三个观察点：

看颜色。Excluded 的目录在 Project 面板里是橙色的，正常源码目录是普通颜色。

试搜索。Cmd + Shift + F（Windows Ctrl + Shift + F）搜一个只在 dist 里出现的字符串，应该搜不到。注意搜索框里的 Scope 要保持默认的 In Project，如果手动切成了 All Places 会连排除的目录一起搜。

看索引进度。改完之后用 File → Invalidate Caches / Restart 重建一次索引，观察底部状态栏的 Indexing... 持续时间。大项目里排除掉 dist 前后能差一倍以上。

索引慢的其它排查方向

排除目录只是其中一环。如果 IDE 还是卡，按影响大小依次看：

1. 堆内存不够。WebStorm 默认最大堆是 2048MB（新版本可能更高），大项目不够用，表现是频繁卡顿、状态栏偶尔弹「Low Memory」。改法：Help → Change Memory Settings，改成 4096 或 8192（不要超过物理内存的一半）。改完重启。

想确认当前用了多少，在 Settings → Appearance & Behavior → Appearance 里勾上 Show memory indicator，状态栏右下角会出现内存占用条。

2. 杀毒软件扫描。Windows 上 Defender 实时扫描 IDE 的索引目录会显著拖慢速度。把这几个路径加进排除列表：项目目录、%LOCALAPPDATA%\JetBrains、IDE 安装目录。macOS 上一般没这个问题，除非装了第三方安全软件。

3. 项目放在网络盘或同步目录里。iCloud Drive、OneDrive、Dropbox、坚果云里的项目，IDE 每次写索引都触发一次同步上传，能慢到无法使用。代码项目一定要放在本地磁盘的普通目录下。

4. 单个超大文件。有时候慢不是因为文件多，而是某个文件特别大（几 MB 的 JSON、mock 数据、日志）。WebStorm 对超过 2.5MB 的文件默认只做语法高亮不做完整解析，但在这个阈值以下的大文件仍然会全量索引。这个阈值可以通过 Help → Edit Custom Properties 加一行调整：

idea.max.intellisense.filesize=1000

单位是 KB。调小之后大文件会被跳过深度分析，代价是那些文件里没有补全和跳转。

5. 插件。装了太多插件（尤其是自己做语法分析的那类）会拖慢索引。Help → Activity Monitor 能看到各插件的 CPU 占用，排掉可疑的再逐个恢复。