🧭 前言：为什么 .idea/ 会带来 Git 污染？

IntelliJ 系列 IDE（包括 IntelliJ IDEA、Android Studio、PyCharm、WebStorm 等）在项目根目录生成一个 .idea/ 文件夹，用于存储 IDE 的配置与状态信息。

这个目录同时包含了：

  • 可共享的项目结构、模块配置、检查规则等；

  • 不应共享的本地化路径（如 JDK、Gradle）、窗口布局、调试状态等。

如果不加选择地上传 .idea/，会导致：

  • 不同系统（Windows ↔ Linux ↔ macOS）路径差异污染 Git；

  • IDE 自动保存状态（如窗口大小、最近运行设备）触发频繁 diff；

  • 格式化风格不一致导致提交记录出现大量无意义的格式改动。

本篇将提供一套通用于 IntelliJ 全系列 IDE 的 .gitignore 配置，并对 Android Studio 补充特化建议。

✅ 可共享的 .idea/ 子项（推荐保留）

💡 说明：对于 Gradle / Maven 项目，初始导入时 .idea/modules.xml 和 .iml 文件可能不会立即生成，
因为模块结构是由 IDE 在读取 build.gradle[.kts] 或 pom.xml 后内部推导出来的，而非直接生成在 modules.xml 中。 一旦在 IDE 中手动设置了排除目录、额外的源码路径、模块依赖关系等行为， IntelliJ 会自动生成 modules.xml 和 .iml 文件并记录这些定制信息。
此时建议将这两个文件提交到 Git，以同步协作中 IDE 的模块边界与排除规则。

文件/目录

内容

上传建议

说明

.idea/modules.xml

模块结构

⚠️ 视项目类型和使用情况而定

初始由 IDE 推导模块结构，若设置了排除目录等自定义项，会生成该文件，应提交

.idea/vcs.xml

版本控制系统设置

✅ 上传

自动识别 Git/SVN 等

.idea/inspectionProfiles/

代码检查规则

✅ 推荐

保持团队一致的代码提示

.editorconfig

代码风格配置

✅ 强烈推荐

跨 IDE 格式统一，已支持 JetBrains 扩展

❌ 推荐忽略的 .idea/ 子项（本地化 / 易污染）

文件/目录

内容

上传建议

原因

.idea/workspace.xml

窗口布局、运行状态等

❌ 忽略

每人不同，频繁变动

.idea/misc.xml

JDK 路径、编码等

❌ 忽略

本地路径强绑定，跨系统污染

.idea/gradle.xml

Gradle JVM 路径等

❌ 忽略

本地化配置，无协作意义

.idea/codeStyles/

JetBrains 专属格式风格

❌ 忽略

使用 .editorconfig 即可

.idea/deploymentTargetSelector.xml

最近连接的设备

❌ 忽略

本地状态

.idea/deviceManager.xml

模拟器状态

❌ 忽略

本地状态

.idea/runConfigurations.xml

运行配置

❌ 忽略

个人化配置，不具移植性

.idea/shelf/

临时保存的变更

❌ 忽略

IDE 本地草稿缓存

📱 Android Studio 特有忽略项

路径

上传建议

原因

local.properties

❌ 忽略

包含本地 SDK 路径，不应共享

.externalNativeBuild/、.cxx/

❌ 忽略

CMake/NDK 构建产物

captures/

❌ 忽略

录屏/调试输出

.kotlin/

❌ 忽略

Kotlin 编译缓存（如 sessions）

📄 推荐 .gitignore 模板（通用 IntelliJ + Android Studio）

# === IntelliJ / JetBrains 系 IDE 配置 ===
.idea/caches/
.idea/codeStyles/
.idea/gradle.xml
.idea/misc.xml
.idea/workspace.xml
.idea/deploymentTargetSelector.xml
.idea/deviceManager.xml
.idea/AndroidProjectSystem.xml
.idea/runConfigurations.xml
.idea/shelf/
.idea/dictionaries/

# === 可共享配置（建议保留，需手动添加）===
# Keep: .idea/modules.xml
# Keep: .idea/*.iml
# Keep: .idea/vcs.xml
# Keep: .idea/inspectionProfiles/
# Keep: .editorconfig

# === 系统杂项 ===
.gradle/
build/
.cxx/
.externalNativeBuild/
captures/
local.properties
.kotlin/

.DS_Store
Thumbs.db
.vscode/

🔍 附录：为什么不建议使用 .idea/.gitignore

虽然 JetBrains 会在 .idea/ 目录内生成一个 .gitignore，提示你忽略某些文件，但这个文件默认不会生效，因为 Git 只会从项目根目录的 .gitignore 开始解析路径。

因此，请始终在项目根目录下集中管理.gitignore，不要依赖 .idea/.gitignore。

📌 实践总结：如何在项目中应用本文规范

以下内容是基于本文所述的 IntelliJ 系 .idea/ 结构与协作策略，整理出的可直接用于项目实际配置的 .gitignore 片段与说明，可直接将它作为一段协作规范嵌入项目 README.md 中。

### 💡 IDE 协作规范：`.idea/` 与 `.gitignore` 策略

本项目使用 IntelliJ 系 IDE（如 IntelliJ IDEA / Android Studio）进行开发。为了保持 Git 提交整洁，避免跨平台差异导致的污染，采用以下规范：

#### ✅ 推荐提交的配置项（具协作意义）：

| 路径                          | 说明                   |
| --------------------------- | -------------------- |
| `.idea/modules.xml`         | 模块结构（若 IDE 已生成，建议提交） |
| `.idea/vcs.xml`             | 版本控制系统配置（如 Git）      |
| `.idea/inspectionProfiles/` | 静态检查规则配置             |
| `.editorconfig`             | 统一代码风格，跨 IDE 支持      |

> 💡 Gradle/Maven 项目初始不一定生成 `.iml` 与 `modules.xml`，但只要你手动排除文件夹、设置源码路径，IDE 会自动生成，它们此时即具协作意义。

#### ❌ 必须忽略的文件（本地状态 / 平台路径）：

* `.idea/workspace.xml`、`.idea/gradle.xml`、`.idea/misc.xml`、`.idea/codeStyles/`
* `.idea/runConfigurations.xml`、`.idea/deviceManager.xml`、`.idea/shelf/` 等 IDE 本地运行与调试配置
* Android Studio 特有产物：`.externalNativeBuild/`、`.cxx/`、`.kotlin/`、`captures/`、`local.properties`

#### 📄 推荐 `.gitignore` 模板（节选）

```gitignore
# IntelliJ / Android Studio
.idea/caches/
.idea/workspace.xml
.idea/misc.xml
.idea/gradle.xml
.idea/shelf/
.idea/codeStyles/
.idea/runConfigurations.xml

# Android 构建产物
.gradle/
build/
.externalNativeBuild/
.cxx/
captures/
local.properties
.kotlin/
```

✅ 总结建议

  • 使用 .editorconfig 统一格式化风格，替代 .idea/codeStyles；

  • 精选 .idea/ 中对协作有价值的文件，其余全部忽略；

  • 对于 Android Studio 衍生的缓存目录、构建产物，全部排除；

  • 将所有规则集中写在项目根路径下的 .gitignore，避免多点分裂管理。

这样处理后，你的项目将具备良好的可移植性、整洁的 Git 提交历史，并对协作成员更友好。