如何通过CI自动生成JavaDoc并部署到GitHub Pages网页

前置准备 #

先在本地确认构建配置正常，别等CI跑了才发现本地生成doc就报错：

• 如果是Maven项目，本地执行mvn javadoc:javadoc，确认能在target/site/apidocs目录下生成完整的JavaDoc文件即可。如果因为注释格式不规范报错，可以在pom.xml的maven-javadoc-plugin配置里添加-Xdoclint:none参数忽略格式校验，避免CI流程因为一点小的注释问题意外中断。
• 如果是Gradle项目，本地执行./gradlew javadoc，确认能在build/docs/javadoc目录下生成完整JavaDoc即可，同样可以在javadoc任务配置里添加Xdoclint:none参数跳过严格格式检查。
  之后打开GitHub仓库的Settings页面，找到Pages设置项，将部署源选择为GitHub Actions，不要选原来的分支部署模式，不然会和CI部署的内容冲突。

配置CI工作流 #

在项目根目录下创建路径为.github/workflows/deploy-javadoc.yml的配置文件，Maven项目可以直接用下面的配置：

name: Deploy JavaDoc to Pages
# 触发条件：推送到main分支时自动执行，也可以按需改成打v开头的版本标签时触发
on:
  push:
    branches: [ "main" ]
# 配置权限，满足Pages部署要求
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build-javadoc:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17' # 改成你项目实际用的Java版本
          distribution: 'temurin'
      - name: Generate JavaDoc
        run: mvn -B javadoc:javadoc
      - name: Upload doc artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # 这里填JavaDoc生成的目录，Gradle项目换成build/docs/javadoc
          path: target/site/apidocs
  deploy:
    needs: build-javadoc
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

如果是Gradle项目，只需要把生成JavaDoc的步骤替换成下面的内容，同时修改上传artifact的路径即可：

- name: Grant execute permission for gradlew
  run: chmod +x gradlew
- name: Generate JavaDoc
  run: ./gradlew javadoc

可选调整 #

• 如果不想每次推代码都更新文档，可以把触发条件改成发布Release或者推送v*格式的版本标签时触发，只对应正式版本更新文档。
• 如果需要存多版本文档，可以在生成目录里按版本号建子目录，部署后就能通过路径访问不同版本的JavaDoc。
• 配置提交推送到GitHub之后，就会自动触发第一次流程，等CI跑完就能直接通过GitHub Pages的地址访问最新的JavaDoc，之后所有代码推送都会自动更新文档，不需要再手动操作。注意别写错文档生成路径，这是最容易导致部署出空白页的问题。

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