Android Studio 和 Gerrit 格式化完全对齐完整方案Android Studio 和 Gerrit 格

Android Studio 和 Gerrit 格式化完全对齐完整方案

核心真相：Gerrit 门禁不是 Android‑Studio 的 Ctrl+Alt+L，是 CI 流水线执行 gradle ktlint /spotless 命令行。IDE 插件只是辅助，命令行才是金标准。IDE 配置再好，提交前不跑命令，依然会被 Gerrit 打回。

一、Kotlin（kt/kts）‑ KtLint

1. 安装插件

Plugins 搜索 ktlint（jmailen），安装重启 AS。

2. KtLint 插件设置（Tools → KtLint）

路径：设置 -> settings -> Tools -> KtLint

Mode：Distract free(recommended)
✅勾选 on save 保存自动格式化
Ruleset version：务必选择 Use project config【最重要】

作用：IDE 直接读取项目 gradle 里写死的 ktlint 版本，和 Gerrit CI 版本一模一样，杜绝版本差异带来格式化结果不一样。如果没有这个选项，升级 ktlint 插件。我选的 Latest [1.8.0]。

Baseline file：项目根目录如果有ktlint‑baseline.xml就选中，没有留空。
Apply / OK

3. CodeStyle 绑定项目.editorconfig

1、项目位置

重要提醒：.editorconfig在项目根目录下；

内容（和Gerrit CI对齐）：

root = true

# 通用文件
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

# Kotlin / Kts 文件 ktlint 规则
[*.{kt,kts}]
indent_size = 4
continuation_indent_size = 4
max_line_length = 100
ktlint_code_style = android

# ========== 尾随逗号配置 ==========
# ktlint‑1.8.0 标准规则ID；Gerrit门禁禁止声明处/调用处尾随逗号，显式关闭该检查
ktlint_standard_trailing-comma-on-declaration-site = disabled
ktlint_standard_trailing-comma-on-call-site = disabled

# IDE格式化行为：不自动添加尾随逗号，对齐Gerrit门禁
ij_kotlin_allow_trailing_comma_on_declaration_site = false
ij_kotlin_allow_trailing_comma_on_call_site = false

# Java 文件
[*.java]
indent_size = 4
continuation_indent_size = 4
max_line_length = 100

# xml 布局、manifest、资源文件
[*.xml]
indent_size = 4
trim_trailing_whitespace = false

# aidl 接口文件
[*.aidl]
indent_size = 4

# gradle groovy
[*.gradle]
indent_size = 4

# properties
[*.properties]
indent_size = 4

注意：修改格式化参数之后不生效？

修改项目 .editorconfig，给 ktlint 关掉该规则：

ini

[*.{kt,kts}]
# 关闭：多行函数声明强制尾随逗号，避免本地和CI冲突
ktlint_standard_trailing-comma-on-declaration-site = disabled
ktlint_standard_trailing-comma-on-call-site = disabled

ij_kotlin_allow_trailing_comma_on_declaration_site = false
ij_kotlin_allow_trailing_comma_on_call_site = false

修改保存；
File -> Reload All from Disk；
这条黄色波浪警告直接消失，ktlint 不会再让你加末尾逗号，和 Gerrit 保持一致。

这条配置只控制本地编辑器提示；Gerrit CI 读取的是它服务器上的 editorconfig，你改本地不会影响 CI。

Reload All from Disk：只重载磁盘文件，速度快，不用重启 IDE（改 editorconfig 首选）
Invalidate Caches：全盘清缓存，会重启 IDE，万不得已再用。

2、配置editorconfig

路径：File → Settings → Editor → Code Style → Kotlin右上角 Set from → Project→ EditorConfig

不要手动修改缩进、换行、import 排序。全部读取项目根目录.editorconfig，这个文件 IDE、ktlint 命令行、Gerrit 共用一套规则。

快捷键Ctrl+Alt+L作为主力，交给 ktlint 插件 on‑save 自动处理。原生格式化和 ktlint 规则存在差异（尾随逗号、import 排序）。

4. 提交前必跑命令（必做，插件会有 bug）

shell

# 自动修复所有可修复格式问题
gradlew.bat  ktlintFormat

# 本地完全复刻Gerrit门禁校验，0错误再提交
gradlew.bat ktlintCheck

Linux/Mac	Windows CMD	Windows PowerShell
`./gradlew ktlintFormat`	`gradlew.bat ktlintFormat`	`.\gradlew.bat ktlintFormat`
`./gradlew ktlintCheck`	`gradlew.bat ktlintCheck`	`.\gradlew.bat ktlintCheck`

✅只要本地ktlintCheck通过，Gerrit ktlint 门禁一定过。

二、Java 代码（绝大多数车载项目使用 google‑java‑format + spotless）

Java 没有 ktlint，用 spotless 插件。

安装插件：google‑java‑format
Settings → Other Settings → Google Java Format 勾选 Enable，把 IDE Java 格式化交给 google java format。

提交前执行命令行：

shell

gradlew.bat spotlessApply   #自动修复
gradlew.bat spotlessCheck   #校验，复刻Gerrit

三、xml/AIDL 文件格式化

AIDL、xml 格式错误 Gerrit 也会拦截。

Settings → Editor → Code Style → XML，Set from → Project
AIDL：Settings → Editor → Code Style → AIDL，Set from → Project

项目一般会把 aidl/xml 格式化规则放在.editorconfig。

四、完整开发工作流（照这个流程，几乎不会出现格式被打回）

写代码，保存文件，ktlint 插件自动格式化 kt/kts。
Java/xml/Aidl 手动 Ctrl+Alt+L。
开发完成，执行：

bash

gradlew ktlintFormat spotlessApply
gradlew ktlintCheck spotlessCheck

4. 命令行无报错，git add，commit，push gerrit。

五、高频踩坑清单

❌IDE 选 Latest 版本，Gerrit 服务器 ktlint 版本不一样：本地 IDE 没问题，Gerrit 报尾随逗号、换行错误。✅解决：Use project config。
❌只依赖 Ctrl+Alt+L 原生格式化 Kotlin。✅解决：开启 ktlint on‑save，由 ktlint 接管 kotlin 格式化。
❌本地 IDE 不跑命令，直接提交 Gerrit。

IDE 插件版本、缓存、bug 会导致 IDE 和命令行输出不一致，命令行才是 Gerrit 真正运行的逻辑。

❌自己手动修改 CodeStyle 的缩进、换行。✅全部交给.editorconfig，不要手动改。

六、如果想彻底禁用 AS 原生格式化干扰

重要提醒：`Settings → Editor → Code Style → Kotlin取消所有手动自定义，全部继承 Project（`.editorconfig`） → EditorConfig。`

作用

Set from → EditorConfig：让 Android Studio 的 Kotlin 格式化（Ctrl+Alt+L）直接读取项目根目录的.editorconfig配置。这样：

IDE 手动格式化快捷键行为，和 gradlew.bat ktlintFormat 脚本行为尽量对齐；
和 Gerrit 门禁 ktlint 规则保持一致。

⚠️重要提醒

界面上方黄色警告：Settings may be overridden by EditorConfig意思：只要项目存在.editorconfig，这个页面的手动设置会被文件覆盖，不要在这里手动改参数，全部改 .editorconfig 文件。

七、其它

1、File Cache Conflict 文件缓存冲突

出现原因：

内存里 Android Studio 编辑器的代码，和磁盘上真实文件内容不一致。多半是 ktlint 插件自动格式化、git 操作、外部工具修改了磁盘文件，但是编辑器还保留旧的内存版本，就弹出这个弹窗。

三个按钮含义

Load File System Changes（蓝色当前选中） 👉 优先选这个（绝大多数场景） 读取磁盘上真实文件，用磁盘版本覆盖编辑器内存里的内容。

ktlint 格式化会写到磁盘，选这个，编辑器同步到格式化之后的最新代码。

Keep Memory Changes保留编辑器内存里你看到的内容，把内存版本写回磁盘，会覆盖掉磁盘已经格式化好的代码。

❗不要随便点这个，会丢掉 ktlint 格式化的结果。

Show Difference查看两边差异，对比内存 vs 磁盘的代码，看完再决定上面二选一。

你的场景（ktlint 格式化之后弹出）

✅直接点：Load File System Changes

ktlint 已经把格式化后的代码写入磁盘；加载磁盘变更，编辑器就会显示格式化完成的文件。

小坑提醒

如果你误点 Keep Memory Changes：磁盘上格式化的代码会被覆盖回未格式化状态，等于 ktlint 格式化白做。

以后怎么减少该弹窗

Settings → Advanced Settings → 勾选 Reload files silently when external changes occur开启后，外部修改磁盘文件尽量自动重载，减少弹出该冲突框。

操作流程总结

执行 ktlint 格式化 → 弹出 File Cache Conflict → 选择 Load File System Changes → 编辑器刷新为磁盘最新文件 → 再看 Problems 面板处理剩余不可自动修复 ktlint 警告。

2、格式化之后有弹窗？

这个弹窗含义

Formatting is completed. Files might still contain ktlint violations which can not be autocorrected.翻译：格式化执行完毕，但文件仍然存在ktlint 无法自动修复的违规项，需要手动修改代码。

✅ 弹窗本身不是报错，只是一个信息提示框，不是故障。只要你的代码里存在至少 1 条不能自动修复的 ktlint 问题，执行格式化（Ctrl+Alt+L / 保存自动 format）就一定会弹出这条提示。

方案 1：保留弹窗（推荐，符合 Gerrit 门禁流程）

弹窗本身不能直接关闭，它的作用是提醒你去看Problems面板：

点底部 Problems 窗口，搜索框输入 ktlint
把列表中全部告警手动修复完成
再次执行格式化，这条提示就不会再弹出来（没有不可自动修复违规时，格式化完成不会弹窗）

工作流：格式化 → 看到弹窗 → 去 Problems 修复所有 ktlint 警告 → 再提交 Gerrit。

Android Studio 和 Gerrit 格式化完全对齐完整方案