如何在Javadoc中利用GitLab令牌访问私有GitLab Pages的依赖项目文档？

核心问题 #

Javadoc的<links>参数会在线拉取目标Javadoc的package-list文件生成交叉链接，但私有GitLab Pages需要认证，直接配置链接会因权限不足失败。GitLab Runner中可用的令牌（如项目访问令牌）可绕过该限制，关键是让Javadoc生成过程借助令牌获取私有Javadoc的必要文件。

可行方案：离线链接+CI预下载 #

1. 配置GitLab CI/CD令牌变量 #

• 在项目的Settings > CI/CD > Variables中添加变量（例如GITLAB_PAGES_TOKEN），值为具备read_pages权限的令牌（项目访问令牌/个人访问令牌均可），建议勾选Masked和Protected保障安全。

2. 在CI脚本中预下载私有Javadoc #

在生成Javadoc的CI job步骤中，用curl携带令牌将目标项目的Javadoc文件下载到Runner本地：

# 创建临时目录存放下载的Javadoc
mkdir -p target/other-project-apidocs
# 下载并解压私有Pages上的Javadoc压缩包
curl -H "Authorization: Bearer $GITLAB_PAGES_TOKEN" -L https://private.gitlab.io/sites/other-project/apidocs/ -o target/other-project-javadoc.zip
unzip target/other-project-javadoc.zip -d target/other-project-apidocs

# 若目标Javadoc是直接目录结构，改用wget递归下载
# wget --header="Authorization: Bearer $GITLAB_PAGES_TOKEN" -r -np -nH --cut-dirs=3 -P target/other-project-apidocs https://private.gitlab.io/sites/other-project/apidocs/

3. 修改POM的Javadoc插件配置 #

将原<links>替换为<linkoffline>，指向本地预下载的Javadoc目录，同时保留线上URL作为最终显示的链接：

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <configuration>
        <linkoffline>
          <!-- 最终Javadoc中显示的线上链接地址 -->
          <url>https://private.gitlab.io/sites/other-project/apidocs/</url>
          <!-- Runner本地预下载的Javadoc目录路径 -->
          <location>${project.build.directory}/other-project-apidocs/</location>
        </linkoffline>
      </configuration>
    </plugin>
  </plugins>
</reporting>

原理说明 #

<linkoffline>参数让Javadoc生成时从本地目录读取package-list等必要文件（规避在线访问的权限问题），但最终生成的文档链接依然指向配置的线上私有Pages地址，用户登录GitLab后即可正常访问这些链接。

内容的提问来源于stack exchange，提问作者Karsten Spang