Flutter 仓库中的 Kotlin 代码如何接入 ktlint：Android Studio 格式化配置实战指南

本指南面向 Flutter 官方仓库的贡献者与 Android/Kotlin 开发者，讲解如何在本仓库的 Kotlin 代码提交流程中避免踩到 CI「analyze 检查失败」的坑。文章将以仓库文档 Kotlin-android-studio-formatting.md 为核心骨架，带你完成 ktlint 插件安装、规则集与 baseline 对齐、.editorconfig 兜底规则配置，并结合 .ci.yaml 与 analyze.dart 源码讲清这套格式化机制在 CI 侧的真实运行方式。读完你可以让 Android Studio 在保存/编辑时自动按 Flutter 仓库的标准格式化 Kotlin，从源头消除 lint 报错。

背景：为什么提交 Kotlin 代码会突然挂掉

Flutter 仓库中所有 Kotlin（.kt / .kts）代码统一使用 ktlint 进行格式化与静态检查（lint）。ktlint 是一套 Kotlin 官方风格的代码格式化/检查工具，它既可作为命令行二进制运行，也可作为 Android Studio 插件提供 IDE 内的自动格式化与问题高亮。

如果你曾经：

1. 提交了 Kotlin 代码，直到 CI 的 analyzer 检查失败才意识到格式不合规；
2. 日常使用 Android Studio 编写代码；

那么好消息是：Android Studio 可以被配置成使用 ktlint 自动应用格式并高亮问题，从而把「提交后失败」前移到「编辑器内即时修复」。

该规则在 CI 侧的真实落地位置是仓库根目录的 .ci.yaml 中 Linux analyze 分片（参见 .ci.yaml 第 364-376 行），它通过 CIPD 依赖声明了要使用的 ktlint 版本：

targets:
  - name: Linux analyze
    recipe: flutter/flutter_drone
    timeout: 60
    properties:
      shard: analyze
      dependencies: >-
        [
          {"dependency": "ktlint", "version": "version_1_5_0"},
          {"dependency": "open_jdk", "version": "version:21"}
        ]

即：CI 的 analyze 阶段会拉取版本标识为 version_1_5_0 的 ktlint（对应 1.5 版本线，文档撰写时约为 1.5）并在整个仓库上执行 lint。因此本地 IDE 中使用的 ktlint 规则集版本，必须与这个 CI 依赖保持一致，否则会出现「本地看着没问题、CI 却报错」的版本错位现象。

Android Studio 接入 ktlint：三步配置

仓库官方文档给出的配置路径非常精简，核心是三步：安装插件 → 对齐规则集与 baseline → 复制 .editorconfig 兜底规则。

第 1 步：安装 ktlint 扩展

在 Android Studio 的插件市场中搜索并安装 ktlint 扩展：

• macOS 上的入口为 Android Studio > Settings > Plugins；
• 搜索关键词：ktlint；
• 安装完成后需重启 IDE 使其生效。

该插件安装后即可接管编辑器内的 Kotlin 自动格式化（Reformat Code）与实时 lint 问题高亮，其底层规则与命令行版 ktlint 一致，从而保证「编辑器所见即 CI 所得」。

第 2 步：对齐 ktlint 规则集版本并设置 baseline

安装插件后，还需要让插件使用与仓库 CI 完全一致的规则集版本和 baseline：

1. 规则集（ruleset）版本：选择与 .ci.yaml 中声明一致的 ktlint 版本（文档撰写时为 1.5，对应上文的 version_1_5_0 CIPD 标识），保证本地格式化行为与 CI 相同。
2. baseline：设置为仓库内的 dev/bots/test/analyze-test-input/ktlint-baseline.xml。

以上两个选项都位于 Android Studio > Settings > Tools > ktlint 设置面板中。

baseline 是什么、为什么要设置

baseline 是 ktlint 的「存量违规豁免清单」。仓库内的 baseline 文件内容形如：

<?xml version="1.0" encoding="utf-8"?>
<baseline version="1.0">
    <file name="dev/a11y_assessments/android/app/src/main/kotlin/com/example/a11y_assessments/MainActivity.kt">
        <error line="1" column="9" source="standard:package-name" />
    </file>
    <file name="dev/benchmarks/platform_channels_benchmarks/android/app/src/main/kotlin/com/example/platform_channels_benchmarks/MainActivity.kt">
        <error line="5" column="9" source="standard:package-name" />
    </file>
    <!-- 其余历史遗留测试工程的 package-name 类豁免条目省略 -->
</baseline>

从文件内容看，baseline 中登记的几乎都是历史遗留测试/示例工程里 standard:package-name 类的既有告警（例如 dev/integration_tests/spell_check、dev/manual_tests/android、dev/tracing_tests/android 等目录下的 MainActivity.kt / MainApplication.kt）。这些是存量问题，不属于本次改动引入，因此被列入豁免清单。

在 Android Studio 的 ktlint 插件中指向同一份 baseline 后，IDE 不会把这些既有文件的历史告警当作新问题高亮，也不会与 CI 结果产生噪声式的不一致——CI 端也使用同一份 baseline，见下文源码佐证。

第 3 步：用 .editorconfig 兜底兼容旧版 Kotlin 的额外规则

Flutter 仓库的 Kotlin 代码目前还使用了一些为了兼容旧版本 Kotlin 而开启的额外规则。这些规则无法通过插件设置面板配置，只能通过 .editorconfig 文件生效，而且该文件必须位于你打开 Android Studio 时的那个根目录中。

具体做法：将测试所用的 .editorconfig 复制一份到你打算用 Android Studio 打开的根目录（即仓库根目录）下。该文件内容为：

[*.{kt,kts}]
# Disable trailing commas to allow compatibility with Kotlin versions less than 1.4.
ij_kotlin_allow_trailing_comma = false
ij_kotlin_allow_trailing_comma_on_call_site = false

这两条规则的含义是：ij_kotlin_allow_trailing_comma（参数列表末尾是否允许尾随逗号）与 ij_kotlin_allow_trailing_comma_on_call_site（调用点是否允许尾随逗号）都设为 false，从而禁止生成尾随逗号，保证代码兼容 Kotlin 1.4 以下版本（尾随逗号是 Kotlin 1.4 才引入的语法能力）。文件通过 [*.{kt,kts}] 节对所有 Kotlin 源码文件生效。

需要注意的关键限制：

• ktlint 的 .editorconfig 配置是按目录层级继承的，插件只读取 Android Studio 打开目录所对应的那棵配置树；
• 因此该副本必须放在你执行「打开项目」时所在的最顶层目录，而不是随便某个子目录，否则这些额外规则不会生效；
• 仓库当前并未在根目录默认放置该文件（它只存在于 dev/bots/test/analyze-test-input/.editorconfig 供测试/CI 使用），所以本地需要手动复制一份作为个人开发环境配置。

仓库内还有一处可参考的 .editorconfig 实例：dev/integration_tests/pure_android_host_apps/host_app_kotlin_gradle_dsl/.editorconfig 使用 ktlint = disabled 对某个子目录整体关闭 ktlint，可见 .editorconfig 正是本仓库用来按目录精细化控制 ktlint 行为的标准机制。

CI 侧的对应实现：analyze.dart 中到底跑了什么

为了让「IDE 配置」与「CI 行为」彼此印证，有必要看看 CI 实际执行 Kotlin 检查的源码实现，即 dev/bots/analyze.dart 中的 lintKotlinFiles 函数（analyze.dart 第 1671-1690 行）：

Future<void> lintKotlinFiles(String workingDirectory) async {
  const baselineRelativePath = 'dev/bots/test/analyze-test-input/ktlint-baseline.xml';
  const editorConfigRelativePath = 'dev/bots/test/analyze-test-input/.editorconfig';
  final EvalResult lintResult = await _evalCommand('ktlint', <String>[
    '--baseline=$flutterRoot/$baselineRelativePath',
    '--editorconfig=$flutterRoot/$editorConfigRelativePath',
  ], workingDirectory: workingDirectory);
  ...
}

这段源码清晰地告诉我们 CI 端的两大事实：

1. CI 显式传入了 --baseline 与 --editorconfig 两个参数，分别指向 dev/bots/test/analyze-test-input/ktlint-baseline.xml 和 dev/bots/test/analyze-test-input/.editorconfig——这与前文要求 Android Studio 中设置的 baseline、复制的 .editorconfig 是同一份来源，正是为了保证本地与 CI 完全等价。
2. 若本机没有 ktlint，CI 会直接报 Failed to find ktlint on PATH. Kotlin code analysis failed.（analyze.dart 第 1679 行），说明该检查强依赖 ktlint 可执行文件，插件与命令行工具本质共用同一套规则引擎。

此外，lintKotlinTemplatedFiles（analyze.dart 第 1629-1669 行）还会把 packages/flutter_tools/templates 下的 Kotlin 模板文件（.kt.tmpl / .kts.tmpl）中 {{placeholder}} 替换为 dummy 值后写入临时目录，再对生成的 Kotlin 文件执行同一套 ktlint 检查——确保 flutter create 模板生成的代码自身也是合规的。这说明仓库对 Kotlin 格式的约束覆盖了「手写代码」与「模板生成代码」两条链路。

本地复现与自查：在提交前主动跑一遍

如果不想依赖 IDE 插件，也可以在提交前按 CI 的错误提示手工复现检查。依据 analyze.dart 第 1680-1687 行 给出的指引：

1. 先到 .ci.yaml 中该 shard 的 dependencies 一节确认当前使用的 ktlint CIPD 版本标识（即 version_1_5_0）；
2. 下载对应版本的 ktlint 可执行文件；
3. 在仓库根目录执行等价于 CI 的命令：

<path_to_ktlint>/ktlint \
  --editorconfig=dev/bots/test/analyze-test-input/.editorconfig \
  --baseline=dev/bots/test/analyze-test-input/ktlint-baseline.xml

其中两条路径均为相对仓库根目录的路径（对应源码中的 $flutterRoot/$editorConfigRelativePath 与 $flutterRoot/$baselineRelativePath）。

当 CI 检查失败时，错误信息还会直接建议「使用 Android Studio 的开发者请阅读 docs/platforms/android/Kotlin-android-studio-formatting.md 启用自动格式化」——这正是本文所依据的文档在整个仓库工具链中的定位：它是官方为 Android Studio 用户准备的「CI Kotlin 检查」配套配置手册。

小结：一次配置，长期省心

把上面三步串起来，Flutter 仓库的 Kotlin 格式化生态是一个完整闭环：

环节	使用的配置/工具	仓库内位置
规则引擎	ktlint（版本与 CI 对齐，当前为 1.5 线）	.ci.yaml（CIPD 依赖 version_1_5_0）
CI 执行入口	lintKotlinFiles / lintKotlinTemplatedFiles	analyze.dart
豁免清单	ktlint-baseline.xml（存量 package-name 告警）	dev/bots/test/analyze-test-input/ktlint-baseline.xml
额外规则	.editorconfig（禁用尾随逗号以兼容 Kotlin < 1.4）	dev/bots/test/analyze-test-input/.editorconfig
IDE 接入	Android Studio ktlint 插件 + 根目录 .editorconfig 副本	本地开发环境

对于 Android Studio 用户，最小化行动清单就是：装 ktlint 插件 → 在 Tools > ktlint 中把版本调到与 CI 一致并指向 ktlint-baseline.xml → 把测试用的 .editorconfig 复制到仓库根目录。完成后，编辑、保存、格式化 Kotlin 代码时 IDE 会即时给出与 CI 完全一致的反馈，避免「提交之后 analyze check 才失败」的被动循环。