arouter-register注解处理器失效怎么办

Question

使用ARouter时，若`arouter-register`注解处理器失效，导致路由表未自动生成，常见原因是模块未正确应用`com.alibaba.arouter.register`插件或Gradle配置缺失。在组件化项目中，常因未在子模块的`build.gradle`中启用注解处理器，或依赖版本冲突导致APT未触发。此外，Android Studio升级后可能禁用注解处理，需检查“Enable annotation processing”是否开启。如何排查并修复`arouter-register`注解处理器不生效的问题？

Answer 1

ARouter 注解处理器失效问题的深度排查与修复方案

1. 问题背景与现象描述

在 Android 组件化开发中，ARouter 作为主流的路由框架，依赖注解处理器（APT）在编译期生成路由表。当 arouter-register 注解处理器未生效时，常见表现为：

• 运行时报错：找不到目标页面（No route found for path）
• Logcat 中提示：ARouter::There is no route match the path
• 生成的 javaDoc 或 build/generated 目录下缺失 ARouter$$Group$$xxx.java 文件

这些问题的根本原因通常指向注解处理器未被正确触发。

2. 常见原因分类与优先级排序

优先级	原因类别	具体表现
高	Gradle 插件未应用	子模块未引入 com.alibaba.arouter.register
高	注解处理关闭	Android Studio 设置中禁用 APT
中	依赖版本冲突	Kapt 与 Gradle 版本不兼容
中	模块未启用 APT	遗漏 kapt 'com.alibaba:arouter-compiler:xxx'
低	缓存问题	旧编译产物干扰

3. 深度排查流程图

graph TD
    A[路由跳转失败] --> B{是否启用 arouter-register 插件?}
    B -- 否 --> C[在 build.gradle 中添加 apply plugin]
    B -- 是 --> D{Android Studio 是否开启注解处理?}
    D -- 否 --> E[File > Settings > Build > Compiler > Annotation Processors]
    D -- 是 --> F{子模块是否配置 kapt 依赖?}
    F -- 否 --> G[添加 arouter-compiler 依赖]
    F -- 是 --> H{是否存在依赖版本冲突?}
    H -- 是 --> I[统一 ARouter 版本 & Gradle 兼容性检查]
    H -- 否 --> J[清理重建 & 检查 generated 文件]

4. 核心解决方案详解

4.1 应用 ARouter Register 插件

在每个使用 @Route 注解的子模块 build.gradle 中必须显式应用插件：

apply plugin: 'com.alibaba.arouter'

android {
    ...
}

dependencies {
    api 'com.alibaba:arouter-api:1.5.2'
    kapt 'com.alibaba:arouter-compiler:1.5.2'
}

注意：com.alibaba.arouter.register 是旧版命名，新版已统一为 com.alibaba.arouter 插件。

4.2 启用 Android Studio 注解处理

路径：File → Settings → Build → Compiler → Annotation Processors

确保勾选“Enable annotation processing”并选择“Obtain processors from project classpath”。

若使用命令行构建，该设置不影响 ./gradlew assembleDebug，但影响 IDE 内部编译。

4.3 正确配置 KAPT 依赖

在 Kotlin 项目中，必须使用 kapt 而非 annotationProcessor：

// Kotlin 模块
kapt 'com.alibaba:arouter-compiler:1.5.2'

// Java 模块
annotationProcessor 'com.alibaba:arouter-compiler:1.5.2'

混合项目建议统一使用 kapt，避免因模块类型导致 APT 失效。

5. 高级排查技巧

5.1 检查生成的源码目录

编译后查看路径：

app/build/generated/source/kapt/debug/com/alibaba/android/arouter/routes/

应存在如下文件：

• ARouter$$Root$$moduleName.java
• ARouter$$Group$$user.java
• ARouter$$Providers$$xxx.java

若目录为空或不存在，说明 APT 未执行。

5.2 Gradle 依赖冲突检测

执行以下命令查看依赖树：

./gradlew :module-name:dependencies | grep arouter

确保所有模块使用相同版本的 arouter-compiler，避免多版本共存导致处理器注册失败。

5.3 清理与强制重建

执行完整清理流程：

./gradlew clean
./gradlew --stop
# 删除 .gradle 缓存目录
rm -rf ~/.gradle/caches/
# 重新构建
./gradlew assembleDebug

可排除因 Gradle 缓存导致的 APT 不触发问题。