Bitbucket Pipelines报错：找不到符号UniversalDetector类

我已经在pom.xml中引入了juniversalchardet依赖，配置如下：

<dependency>
    <groupId>com.googlecode.juniversalchardet</groupId>
    <artifactId>juniversalchardet</artifactId>
    <version>1.0.3</version>
</dependency>

我的bitbucket-pipelines.yml配置是这样的：

image: maven:3.3.3
pipelines:
  default:
    - step:
        caches:
          - maven
        script:
          - mvn clean install -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.insecure=true

本地环境下可以正常下载依赖并完成构建，但在Bitbucket Pipelines中构建时出现了以下错误：

[ERROR] /opt/atlassian/pipelines/agent/build/src/main/java/package/location/GuessedEncoding.java:[18,15] cannot find symbol
symbol: class UniversalDetector

我推测是Pipelines无法找到对应的Maven构件，请问我的流水线配置是否存在问题？

排查与解决方案 #

咱们一步步来分析可能的问题，试试下面的方法：

1. 先排查Maven缓存的问题 #

你启用了Maven缓存，这本来是提升构建速度的好办法，但如果缓存里还没有这个新引入的依赖，或者缓存的依赖文件损坏，就会导致编译失败。可以先临时禁用缓存试试：
修改bitbucket-pipelines.yml，注释掉缓存配置：

image: maven:3.3.3
pipelines:
  default:
    - step:
        # caches:
        #   - maven
        script:
          - mvn clean install -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.insecure=true

如果这次构建成功了，说明之前的缓存有问题。之后可以重新启用缓存，下次构建就会把正确的依赖缓存起来了。

2. 升级Maven镜像版本 #

你用的maven:3.3.3是个比较老的版本（2015年发布的），它对现代HTTPS仓库的支持可能存在兼容性问题，哪怕你加了SSL相关的参数也可能出问题。建议换成较新的Maven镜像，比如maven:3.8.6（LTS版本）或者最新的稳定版：

image: maven:3.8.6
pipelines:
  default:
    - step:
        caches:
          - maven
        script:
          - mvn clean install -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.insecure=true

新版本的Maven在依赖解析、SSL处理上都更完善，大概率能解决这类问题。

3. 确认依赖范围是否正确 #

检查一下你的pom依赖有没有设置错误的<scope>，如果不小心写成了test或者provided，主代码编译时就会找不到这个类。默认的compile范围是正确的，你可以明确写出来确保没问题：

<dependency>
    <groupId>com.googlecode.juniversalchardet</groupId>
    <artifactId>juniversalchardet</artifactId>
    <version>1.0.3</version>
    <scope>compile</scope> <!-- 明确指定编译范围，主代码可访问 -->
</dependency>

4. 确保Maven能访问中央仓库 #

有时候本地的settings.xml配置了私有仓库或镜像，但Bitbucket Pipelines用的是默认配置，可能导致无法拉取中央仓库的依赖。你可以在pom里直接添加中央仓库的配置，确保依赖能被找到：
在pom.xml的<project>节点下添加：

<repositories>
    <repository>
        <id>maven-central</id>
        <url>https://repo1.maven.org/maven2/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
    </repository>
</repositories>

5. 强制更新依赖 #

在构建命令里加上-U参数，强制Maven检查并更新所有依赖，哪怕本地有缓存也会重新拉取最新的版本：

mvn clean install -U -Dmaven.wagon.http.ssl.allowall=true -Dmaven.wagon.http.ssl.insecure=true

这个参数能避免因为缓存的依赖过时或损坏导致的问题。

内容的提问来源于stack exchange，提问作者Jed Cua