项目模型、索引与缓存
同一份代码在终端能构建，在 IDE 里却满屏报红；清缓存后短暂恢复，第二天又复发。这类问题常被归结为“IDE 抽风”，但真正的原因通常是项目模型出现了分叉：团队认为仓库根在 A，IDE 打开的根在 B；构建工具使用 JDK 21，语言服务使用 JDK 17；生成代码已经被编译器消费，却没有进入索引；本地手工添加的依赖让作者机器可用，却无法由干净 clone 重建。
架构治理的关键不是记住四套菜单，而是建立共同真相：仓库中的构建描述和 wrapper 定义可重建模型，IDE 导入并派生编辑模型，索引只是这个模型的加速产物，缓存更不是配置真相源。只有沿着这条链路取证，clean 才有意义。
先建立统一模型：五层事实不能混在一起
第一层是仓库事实：版本控制根、构建文件、wrapper、锁文件、源码、生成规则和团队共享配置。第二层是构建模型：构建工具解析出的模块、依赖图、source set、target framework、编译选项和输出目录。第三层是 IDE 派生模型：IDE 把构建模型映射成 workspace、module、solution/project、classpath 或 language-server workspace。第四层是索引：符号、引用、类型、文件摘要和外部库元数据。第五层是缓存与 UI 状态：窗口布局、最近文件、下载索引、增量编译状态、断点和本地历史。
出现问题时必须按层排查。仓库事实错误，清索引不会修复；SDK 选择错误，删除 UI 状态无效；只有模型正确而索引损坏时，invalidate cache 才是对症操作。
安装、版本、账号和远程边界
交叉验证不要求一台机器同时安装四套 IDE，但每种受支持入口都要来自官方发行渠道，并记录产品版本、更新通道、插件版本和 SDK。VS Code 使用 Stable 或 Insiders发行版；JetBrains 通过 Toolbox App 或安装包；Eclipse 从官方 Installer/Packages选择发行包；Visual Studio 通过 Visual Studio Installer选择 edition、channel 与 workload。
账号不是项目模型的真相源。VS Code Settings Sync 主要同步个人设置、快捷键和扩展，官方明确说明它不会把扩展同步到 Remote SSH、Dev Container 或 WSL 窗口。JetBrains 账号负责订阅和部分个人设置同步，不能代替 Maven/Gradle 项目描述。Eclipse 的工作区模型主要落在 workspace metadata 和项目文件，不依赖云账号。Visual Studio 登录涉及订阅、试用和个性化；Community 的使用范围也不能简单概括为“企业免费”。团队在采用前应按官方 edition/订阅条款核对，而不是把个人登录状态写进项目基线。
远程开发时，项目模型和索引通常在运行语言后端/IDE backend 的那一侧。代码在容器或远端主机，SDK 和依赖也应在那里可见；本地 UI 同步成功不代表远端扩展、语言服务器和缓存已同步。企业能力应落到受控版本、软件源、扩展准入、远程后端镜像和审计，不应依赖某位成员的账号漫游状态。
版本治理也要看支持通道。Visual Studio 2022 版本的 Community 只支持 Current channel 的最新受支持版本，Professional/Enterprise 可按官方 LTSC 口径管理；JetBrains、VS Code 与 Eclipse 的更新节奏不同，不能用统一“半年升一次”替代产品支持策略。实验性/预览功能应在代表仓库验证后再进入基线。
四类 IDE 如何表达同一个仓库
VS Code：folder 或 multi-root workspace
VS Code workspace 是一个窗口中打开的一个或多个 folder。单 folder 时，打开的目录通常就是项目根；multi-root workspace 用 .code-workspace 文件组合多个 folder，并可保存 workspace settings、tasks 和 launch 配置。VS Code 本身不强制统一项目模型，真正的 module/依赖关系通常由语言扩展和构建工具解释。
从终端打开仓库根：
git rev-parse --show-toplevel
code .如果只打开 src/，语言服务器可能找不到仓库根的 package.json、pom.xml、gradlew、Directory.Build.props 或 .git，于是把源码目录误当 workspace。.vscode/settings.json 可以共享项目设置，但不得写绝对 SDK 路径、账号、token 或真实内网 URL。多根 workspace 还要确认每个 folder 的语言服务是否分别启动，以及跨根引用是否由构建模型支持，而不是仅在 Explorer 中看起来位于同一窗口。
JetBrains：project、module、content root 与 SDK
JetBrains project 模型把 project 定义为顶层容器，一个 project 可以包含多个 module；module 再关联 content root、source/test/generated/excluded 目录、SDK 和依赖。当前帮助已把旧称 indexing 表述为 project analysis，这不改变核心判断：分析结果依赖正确的项目模型。
对于 Maven/Gradle 项目，应从构建文件导入，依赖修改回到构建文件。JetBrains 官方明确说明，使用 Maven/Gradle 时不要只在 Project Structure 中手工添加依赖，否则 IDE 原生模型与构建模型会分叉。Project SDK、Gradle JVM、Maven runner JDK 和语言 toolchain 可能不是同一设置；项目能导入不代表运行和测试使用了同一 JDK。
.idea 中有可共享项目设置，也有用户状态。是否提交应按 JetBrains 官方建议和团队规则精确选择，不能整目录一律提交或一律忽略。绝对路径、数据库连接、部署目标和个人运行历史不得进入仓库。
Eclipse：workspace、project 与 builder
Eclipse workspace 是工作台状态和多个 project 的容器，project 可以位于 workspace 目录内，也可以链接到其他位置。.project、.classpath 和项目 .settings/ 可能属于可共享模型；workspace 下的 .metadata 是机器/用户状态，不应提交，也不应复制为团队模板。
Eclipse builder 基于增量状态工作。Eclipse 构建说明明确 Project > Clean 会丢弃已有 build state，下一次构建重新处理资源。这里的 clean 不是删除整个 workspace。导入失败时先检查项目 nature、builder、JRE、classpath container 和构建工具同步，再决定是否新建 workspace；直接删除 .metadata 会同时丢失大量取证和个人状态。
Visual Studio：solution、project 与 folder mode
Visual Studio 的 project 通常对应 .csproj、.vcxproj 等 MSBuild 项目文件；solution 与 project分别承担多项目容器和构建单元职责。.suo 等用户状态通常位于隐藏的 .vs 目录。solution folder 只是 Solution Explorer 中的虚拟分组，不是磁盘目录，也不改变构建依赖。
Visual Studio 也支持直接 Open Folder，适合某些 CMake、文件夹或轻量场景，但 folder view 与 solution/project view 的能力和配置入口不同。团队应明确标准入口是 .sln、.slnf、项目文件还是 folder，不能有人打开 solution、有人打开源码子目录，却用“都是同一份代码”解释结果差异。
SDK 是模型输入，不只是一个可执行文件
IDE 至少要回答四个问题：解析代码用哪个 SDK，构建用哪个 SDK，运行/测试用哪个 SDK，语言服务器从哪里读取标准库。它们可能来自系统 PATH、IDE bundled runtime、项目设置、构建 daemon、toolchain 文件或容器镜像。
先在终端记录基线：
java -version
./mvnw -version
./gradlew --version
node --version
dotnet --info只执行项目实际使用的命令。预期 wrapper 输出的 JVM、Gradle/Maven、Node 或 .NET SDK 与仓库声明一致。然后在 IDE 的项目结构、语言状态、构建输出中记录同类版本。若 CLI 与 IDE 不同，优先修正 SDK 选择和启动环境；不要先清缓存。
Windows 从桌面图标启动 IDE 与从已初始化的开发者终端启动，PATH 和环境变量可能不同。macOS GUI 应用也可能不继承交互式 shell 配置。把关键版本写进仓库可声明文件或版本管理器配置，比要求成员“先手工 export”更可靠。机器私有 SDK 绝对路径不应提交。
依赖模型：构建文件是主，IDE 映射是从
IDE 为了导航和补全会建立自己的依赖视图，但团队必须能从构建描述重建它。Maven/Gradle 项目在构建文件里改依赖，Node 项目在 package.json 与 lockfile 中改，.NET/C++ 项目在项目文件、props/targets、CMake 或包配置中改。IDE 的“Add Library/Reference”只有在它同步修改了受版本控制的权威文件时才算完成。
验证分叉最有效的方法不是看依赖树截图，而是比较两次构建：
# JVM 项目按仓库实际 wrapper 二选一
./mvnw test
./gradlew test
# Node 项目使用仓库锁定的包管理器
npm ci
npm test
# .NET 示例
dotnet restore
dotnet build --no-restore预期 CLI 成功，IDE 调用同一 configuration 时也成功。若 IDE 成功而 CLI 失败，通常存在本地手工依赖、IDE 专用 compiler、未提交生成物或环境变量；这比“IDE 更智能”更危险，因为 CI 和新成员无法复现。
具体依赖冲突、私服、代理和缓存解析应转到包管理、构建与任务脚本专题。当 IDE 导入已经能稳定复现、故障却发生在依赖解析或构建任务内部时，继续清理索引通常不会解决根因。
生成目录：既要被构建消费，也要避免污染索引
生成代码、编译输出和下载依赖不是一类东西。生成源码可能需要进入 IDE source set，编译输出应排除，依赖缓存应位于项目外或受控缓存目录。常见目录包括 target/generated-sources、build/generated、dist、out、bin、obj、.gradle、node_modules，但不能仅凭名字删除；先看构建配置和版本控制状态。
生成源码缺失时，IDE 常报“类型不存在”，CLI 在执行 generate 阶段后却成功。正确修复是让构建导入声明生成任务与 generated source root，或在项目 bootstrap 中先生成；不要把生成代码手工复制进 src/。反过来，如果把 target、build、dist、node_modules 全部纳入通用索引，文件监听、符号扫描和磁盘都会膨胀。
用下面的非破坏性命令先识别体积和 Git 状态：
git status --short
git check-ignore -v target build dist out bin obj node_modules 2>/dev/null
du -sh target build dist out bin obj node_modules 2>/dev/nullPowerShell 可以按已知目录逐个执行 Get-ChildItem/Measure-Object，不要在未知根目录递归删除。预期生成/输出目录被忽略，权威源码和构建描述保持可追踪。IDE 的 exclude 只是性能提示，不等于 Git ignore，也不等于构建 clean。
索引与缓存到底保存了什么
索引通常保存文件摘要、符号、引用、类型关系、外部库元数据和搜索结构；缓存可能再包含文件系统快照、下载的共享索引、语言服务器数据库、增量编译结果、UI 状态和本地历史。它们的共同特点是“应该可由权威输入重建”，但删除成本和影响范围不同。
VS Code 的索引多由各语言扩展维护，因此不存在一个对所有语言都正确的“清 VS Code 缓存”按钮。以 C/C++ 扩展为例，官方提供 IntelliSense cache path/size，并允许将 size 设为 0 排查缓存导致的磁盘写入；Java、TypeScript、Python 等扩展有自己的重启或清理语义。先确认是哪个扩展产生缓存。
JetBrains 的 Invalidate Caches会影响当前 IDE 版本曾打开的所有项目，重启后重建。Local History 默认不会随普通 invalidate 删除，除非显式选择相关选项。这个操作范围很大，应在模型、SDK、导入日志都正确后使用，并记录重建时间和失败现象。
Eclipse 的 workspace .metadata 含工作台和插件状态，JDT/CDT/PDE 又各有索引与 builder state。Project > Clean 只处理构建状态；新 workspace 是更强的隔离实验；删除 .metadata 是最后手段。Visual Studio 的 .vs、.suo、组件模型缓存、IntelliSense 数据库与项目 bin/obj 也属于不同层，Clean Solution 官方定义主要是删除中间/输出文件，不等于清空所有 IDE 状态。
因此“清缓存”必须说出完整宾语：清哪个产品、哪个插件、哪个项目、哪类数据、是否保留 Local History/断点、重建来源是什么。没有这些信息的团队脚本不应执行。
用一个失效反例区分权威输入与派生结果
下面的隔离实验不依赖具体 IDE。它先把生成文件留在工作副本里，再修改权威输入而故意不重新生成，用来模拟“IDE 仍能看到旧符号，干净环境却失败”的现场：
mkdir project-model-lab && cd project-model-lab
git init
mkdir schema generated
printf 'v1\n' > schema/version.txt
cp schema/version.txt generated/version.txt
printf 'generated/\n' > .gitignore
git add schema/version.txt .gitignore
git commit -m "建立模型基线"
printf 'v2\n' > schema/version.txt
test "$(cat schema/version.txt)" = "$(cat generated/version.txt)"最后一条命令应退出非零：仓库事实已经是 v2，被忽略的派生文件仍是 v1。如果 IDE 或本地构建只消费 generated/version.txt，它可能继续展示旧模型；而新 clone 根本没有这个文件。正确修复不是把 generated/ 纳入版本控制，也不是清除所有 IDE 状态，而是让构建入口显式执行生成动作：
cp schema/version.txt generated/version.txt
test "$(cat schema/version.txt)" = "$(cat generated/version.txt)"
git status --short此时比较命令退出 0，git status --short 只显示权威输入 schema/version.txt 的修改，不应出现 generated/version.txt。实验完成后退出目录并删除整个 project-model-lab；不要把这组命令对准真实仓库。这个反例给出了判断标准：能够删除重建的是派生结果，决定重建内容的是权威输入，两者不能颠倒。
Windows PowerShell 5.1 可以用同样的判断重放关键步骤，不依赖 Bash：
Set-Content -Encoding Ascii schema/version.txt 'v2'
$stale = (Get-Content -Raw schema/version.txt) -eq `
(Get-Content -Raw generated/version.txt)
if ($stale) { throw '反例没有制造出旧生成物' }
Copy-Item schema/version.txt generated/version.txt -Force
$fixed = (Get-Content -Raw schema/version.txt) -eq `
(Get-Content -Raw generated/version.txt)
if (-not $fixed) { throw '生成动作没有恢复一致性' }
git status --shortPowerShell 的预期证据与 Bash 相同：第一次比较为假，复制后为真，Git 状态不出现 generated/。若脚本运行在 Windows PowerShell 5.1，不要使用只有 PowerShell 7 才支持的编码枚举或参数；团队验证脚本本身也属于工具链合同。
最小验证：从新 clone 证明模型可重建
最有说服力的验证不是作者机器上的绿色状态，而是一份新的工作副本。建议在临时目录新 clone，而不是对当前工作区执行危险的 git clean -xfd：
git clone <占位仓库URL> project-model-smoke
cd project-model-smoke
git status --shortgit status --short 应为空。接着按仓库 README 使用 wrapper 安装/构建/测试，保存版本、命令、退出码和日志。随后从仓库根用标准入口打开 IDE，等待导入和索引结束，验证至少一个跨文件跳转、一个外部依赖符号、一个生成类型和一次 IDE 构建。
预期结果不是“界面没有红线”，而是以下证据彼此一致：CLI 与 IDE 使用同一 SDK 大版本；module/project 数量与构建模型一致；generated source 可导航但输出目录被排除；IDE 构建没有引用未提交文件；重启后模型稳定。测试完成后关闭 IDE，删除整个临时 clone 即可回滚，不触碰原工作区。
CLI 与 IDE 不一致的排障主线
现象一：CLI 成功，IDE 报类型或依赖不存在
先判断 IDE 是否打开了正确根、项目是否按构建文件导入、SDK 是否一致、生成任务是否运行。查看 IDE 的构建/导入日志，而不是只看 Problems 面板。常见原因是打开 src/、语言服务未找到 workspace marker、构建 daemon 使用不同 JDK、依赖同步失败或 generated source 未标记。
修复后重新同步项目，等待分析完成，再打开原报错文件。再验证时必须同时跑一次 CLI 构建，确保没有为了让 IDE 变绿而创建本地专用配置。
现象二：IDE 成功，CLI 或 CI 失败
这是优先级更高的治理故障。检查 IDE 是否手工添加 library/reference、是否使用内置编译器、是否读取未声明环境变量、是否编译了工作区外文件，或作者机器是否残留生成物。将 IDE 变更还原为构建文件变更，并在新 clone 重跑。只有 CLI/CI 恢复后，IDE 绿色才可信。
现象三：索引持续运行、风扇高转或文件监听耗尽
先记录哪个进程占 CPU/IO、分析阶段正在扫描什么目录、项目根是否误设为主目录，以及 build、node_modules、日志、挂载目录是否被纳入。大型 monorepo 可以使用 VS Code multi-root 的精确 folder、JetBrains module unload/共享索引、Visual Studio .slnf 等产品能力缩小加载范围，但前提是不会隐藏真实依赖或漏测。
修复 exclude/generated 规则后重启一次并计时。预期分析最终收敛，文件变更只触发受影响范围。若只靠增加内存或定时清缓存维持，根因仍未解决。
现象四：磁盘空间持续下降
把空间按所有者拆分：仓库输出、包管理器缓存、IDE 系统目录、语言服务器缓存、日志、本地历史、多个 IDE 版本和远程 backend。记录目录大小、最近修改时间、进程占用和重建来源。JetBrains cache 可能覆盖该 IDE 版本打开过的多个项目，Visual Studio Installer 的下载缓存与项目 .vs 也不是同一目录。
只清理明确可再生且不再被进程使用的目录。企业机器应对 IDE cache、共享索引、远程 backend 和构建缓存分别设容量基线与告警；单纯给系统盘扩容会延迟故障，但不会建立 owner。
现象五：清缓存后仍然错误
这反而是重要证据：问题多半位于仓库事实、SDK、依赖模型、权限、网络或插件。回到新 clone 的 CLI 基线，对比 IDE 进程环境和导入日志。不要连续执行 invalidate、删 .idea、删 .metadata、删 .vs，否则会把原始差异一起抹掉。
干净重建的证据阶梯
干净重建不是一个按钮，而是一组从轻到重的实验。
第一阶只重载/重新同步项目模型，保留索引与用户状态。第二阶重启语言服务或 IDE，验证是否为进程状态。第三阶执行构建工具自己的 clean，再用 wrapper 构建，验证生成物和增量状态。第四阶只失效目标索引/缓存，记录范围和重建时间。第五阶在新 workspace 或新 clone 导入，隔离用户状态。只有前五阶证据都指向 IDE 系统目录损坏，才考虑删除更大范围状态。
每一阶都记录相同字段：仓库 commit、IDE/插件版本、SDK、打开入口、命令、退出码、错误文本、目录大小、操作前后差异。成功标准是错误消失且新 clone 可复现，不是“重启后暂时没看到”。
Visual Studio 的 Build > Clean Solution 删除中间和输出文件，随后 Rebuild 全量构建；Eclipse Project > Clean 丢弃 builder state，下一次构建重建；JetBrains Invalidate Caches 在重启后重建 IDE 缓存；VS Code 必须按语言扩展选择 restart/clean。这四种动作名字相似，作用层完全不同，不能写成一条跨 IDE 的通用“删除缓存”命令。
清理与回滚
项目模型变更的回滚优先使用版本控制恢复本次受控配置，再重新导入。删除生成物前先确认 git status 干净且目录确实可由构建生成。避免在文章或团队脚本中提供无边界的 rm -rf、Remove-Item -Recurse 或 git clean -xfd。
IDE 状态清理前，导出或截图必要的 SDK、模块、插件和错误日志，但截图必须脱敏。JetBrains invalidate 对话框中涉及 Local History、VCS Log、JCEF 的选项应按故障选择；Eclipse 新建 workspace 比覆盖旧 .metadata 更易回滚；Visual Studio 可先关闭 solution、重命名项目级 .vs 做对照，确认有效后再删除备份；VS Code 先禁用目标扩展并使用新的 profile/窗口验证。
清理后的再验证必须回到原始故障动作，并补一次 CLI 构建。否则只能证明“目录被删除”，不能证明项目模型已修复。
架构选型：项目容器应服务构建边界
小型单仓单应用通常一个 folder/project/solution 足够。多模块仓库需要让 IDE 容器反映构建图，而不是为了界面整齐随意合并。VS Code multi-root 适合组合相对独立的 folder；JetBrains module 适合表达同一 project 中的内容根和依赖；Eclipse workspace 适合承载多个 project，但 workspace metadata 不是共享构建定义；Visual Studio solution 适合组织 MSBuild project，超大 solution 可用 .slnf 减少加载项目。
选择标准是：新成员能否从仓库文件重建，CLI/CI 是否共享同一依赖和 SDK，跨模块导航是否准确，加载范围是否可控，远程后端是否拥有完整工具链。不要为了跨 IDE 一致而提交每种产品的全部内部状态；应共享权威构建模型、格式约定和最小项目设置，让各 IDE 生成自己的可再生索引。
权限、凭证与敏感信息
项目导入会执行或解析构建脚本、任务、插件、code generator 和包管理器 hook；陌生仓库不是静态文本。先在受限环境审查，再允许运行任务。VS Code Workspace Trust会在 Restricted Mode 中限制任务、调试、workspace settings 和部分扩展，但官方也明确提醒恶意扩展仍可能忽略该边界。JetBrains Safe Mode、Visual Studio trust settings 等同样只能降低部分风险，不能替代扩展和构建供应链治理。
.vscode、.idea、Eclipse .settings/launch、.sln 周边配置可能包含绝对路径、内部 package source、账号、证书路径、远程目标、环境变量和服务 URL。项目文件中只保留无密钥模板与相对路径；凭证放系统凭证存储、短期令牌或受控 secret 注入。索引、Local History、日志和 crash dump 也可能包含源码与路径，上传工单前必须脱敏。
团队治理与长期维护
团队应给项目模型指定 owner：构建 owner 维护 wrapper、SDK/toolchain 和依赖描述；IDE owner 维护最小共享设置、插件兼容和导入手册；平台团队维护软件源、远程 backend、缓存容量和审计。任何手工 IDE 修复若不能转化为仓库声明或明确的机器基线，都应记录为临时措施并设到期时间。
在合并请求或 CI 中验证锁文件、wrapper、生成代码策略和禁止提交的 IDE 用户状态。准备至少一个代表仓库做升级冒烟：新 clone、CLI 构建、四类 IDE 中团队实际支持的入口、跨模块跳转、生成源码、测试和干净重建。大型团队还应记录首次索引时间、稳定磁盘占用和增量响应基线，出现明显回归时阻断升级。
最终目标不是让所有人界面一致，而是让任何受支持 IDE 都从同一仓库事实得到相容模型；索引坏了可以重建，缓存满了可以定位，成员换机或远程开发仍能拿出证据证明“这份项目为什么能工作”。
团队自检：能否从空机器解释每一层状态
标准打开入口明确到仓库根、.code-workspace、project、workspace、.sln 或 folder mode，没有让成员凭最近项目列表猜测。wrapper、锁文件、SDK/toolchain 声明和生成规则都在版本控制中，新 clone 不依赖作者机器上的手工 library、环境变量或残留生成物。CLI 与 IDE 的 SDK 大版本、模块数量、依赖来源和生成目录一致；至少一条跨模块导航与一次 IDE 构建有可重复证据。
输出目录、依赖缓存、日志和挂载目录没有进入通用索引；首次分析时间、稳定磁盘占用和增量更新时间有代表仓库基线。每种“clean”都写清产品、插件、项目、状态类型、影响范围和重建来源，没有共享无边界删除脚本。扩展和插件来自批准的软件源，发布者、版本、权限、遥测、许可证与升级回退责任可追踪；受限模式没有被全局关闭来换取方便。
缓存、共享索引、远程 backend 和 Local History 分别有容量 owner；达到阈值时先按目录与进程取证，不靠定期清空掩盖模型分叉。配置、日志、索引和崩溃转储不包含真实 token、内部地址或未脱敏源码；离职、换机和远程环境销毁包含凭证撤销与状态清理。IDE 升级必须通过代表仓库的新 clone、导入、分析、生成、调试和回滚实验；失败时能够恢复上一受控版本，而不是继续污染共享项目文件。