通过Gradle/Maven导入后无法使用自定义库类的问题排查

问题诊断 #

你遇到的「Java file outside source root」错误，本质是IDE无法将导入的Jitpack库识别为可依赖的二进制构件，而是把它当成了未纳入项目编译路径的源码文件。根源出在库的Gradle构建配置存在重复定义、构件打包不规范，导致Jitpack生成的依赖包不符合Maven标准结构。

修复步骤 #

1. 合并重复的Java配置 #

原build.gradle中有两段重复的java配置块，会导致Gradle构建逻辑冲突，删除重复部分，合并为统一配置：

def targetJavaVersion = 17
java {
    withSourcesJar()
    withJavadocJar()
    def javaVersion = JavaVersion.toVersion(targetJavaVersion)
    sourceCompatibility = javaVersion
    targetCompatibility = javaVersion
    if (JavaVersion.current() < javaVersion) {
        toolchain.languageVersion = JavaLanguageVersion.of(targetJavaVersion)
    }
}

2. 规范Maven发布配置 #

自定义jar任务的archiveFileName会破坏Maven构件的标准命名规则，导致Jitpack生成的依赖包无法被IDE正确解析。推荐采用以下方案：

方案一：删除自定义jar命名（优先选择）

移除这段破坏规范的代码：

jar {
    archiveFileName = 'Library.jar'
}

让Gradle使用默认的[artifactId]-[version].jar命名，完全符合Maven规范。

方案二：保留自定义命名并关联到发布

如果必须自定义文件名，修改发布配置明确关联构件：

publishing {
    publications {
        maven(MavenPublication) {
            from components.java
            groupId = 'com.nickname'
            artifactId = 'library'
            version = '1.0.4'
            artifact jar // 关联自定义命名的jar包
        }
    }
}

3. 添加Jitpack构建配置文件 #

在项目根目录创建jitpack.yml，强制指定JDK版本和构建命令，确保Jitpack正确生成符合要求的构件：

jdk:
  - openjdk17
install:
  - ./gradlew publishToMavenLocal

4. 重新发布并验证 #

• 将修改后的代码推送到GitHub仓库
• 前往Jitpack页面，重新构建目标版本（或打新标签如1.0.5避免缓存问题）
• 在测试项目中更新依赖版本，执行Gradle Sync

验证Jitpack构件 #

在Jitpack的版本详情页，确认生成了三个标准构件：

• library-1.0.4.jar（主二进制包）
• library-1.0.4-sources.jar（源码包）
• library-1.0.4-javadoc.jar（文档包）
  同时检查pom.xml中的groupId、artifactId、version是否与依赖坐标完全一致。

修改后的完整build.gradle示例 #

plugins {
    id 'java'
    id 'maven-publish'
}

group = 'com.nickname'
version = '1.0.4'

repositories {
    mavenCentral()
    maven {
        name = "sonatype"
        url = "https://oss.sonatype.org/content/groups/public/"
    }
}

def targetJavaVersion = 17
java {
    withSourcesJar()
    withJavadocJar()
    def javaVersion = JavaVersion.toVersion(targetJavaVersion)
    sourceCompatibility = javaVersion
    targetCompatibility = javaVersion
    if (JavaVersion.current() < javaVersion) {
        toolchain.languageVersion = JavaLanguageVersion.of(targetJavaVersion)
    }
}

tasks.withType(JavaCompile).configureEach {
    if (targetJavaVersion >= 10 || JavaVersion.current().isJava10Compatible()) {
        options.release = targetJavaVersion
    }
    options.encoding = "UTF-8" // 合并编码配置，避免重复定义
}

processResources {
    def props = [version: version]
    inputs.properties props
    filteringCharset 'UTF-8'
}

publishing {
    publications {
        maven(MavenPublication) {
            from components.java
            groupId = 'com.nickname'
            artifactId = 'library'
            version = '1.0.4'
        }
    }
}

内容的提问来源于stack exchange，提问作者Виктор Туманов