未注册私人Julia包MFF的GitHub Pages文档部署问题

问题背景 #

个人Julia包MFF部署GitHub Pages时CI报错：

ERROR: expected package MFF [99a43ef4] to be registered

原因是CI默认尝试从官方注册表安装包，但未注册包无法通过此方式获取，需改为本地引用。

分步解决方案 #

1. 配置docs环境的Project.toml #

在docs/Project.toml中添加本地包依赖，避免从注册表查找：

[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
MFF = "99a43ef4-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # 替换为你的包UUID

[compat]
Documenter = "~0.27" # 匹配使用的Documenter版本
julia = "1.8"

# 关键：添加本地路径引用
[dev-deps]
MFF = { path = ".." }

2. 修改CI工作流脚本 #

替换.github/workflows/docs.yml内容，确保CI优先安装本地包：

name: Documentation

on:
  push:
    branches: [main] # 你的主分支名称
  pull_request:

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: julia-actions/setup-julia@v2
        with:
          version: '1.8' # 匹配你的Julia版本
      - name: Install dependencies
        run: |
          # 根目录环境安装本地包
          julia --project -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
          # docs环境安装本地包
          julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
      - name: Build and deploy docs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
        run: julia --project=docs docs/make.jl

3. 处理密钥生成（DocumenterTools.genkeys()） #

• 无需在特定环境执行，本地任意Julia环境安装DocumenterTools后运行：

  using DocumenterTools
  DocumenterTools.genkeys()
  

• 生成的公钥：添加到仓库Settings > Deploy keys，勾选Allow write access
• 生成的私钥：添加到仓库Settings > Secrets > Actions，命名为DOCUMENTER_KEY

4. 确认docs/make.jl配置 #

确保deploydocs部分指向正确仓库：

using Documenter, MFF

makedocs(
    sitename = "MFF",
    format = Documenter.HTML(),
    modules = [MFF],
    pages = [
        "Home" => "index.md",
        # 按需添加其他文档页面
    ]
)

deploydocs(
    repo = "github.com/shayandavoodii/MFF.git",
    devbranch = "main", # 你的主分支
)

关键说明 #

• 用Pkg.develop替代Pkg.add，让CI直接从本地代码安装包，跳过注册表检查
• gh-pages分支无需手动维护，CI会自动构建并推送文档内容

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