GHCR全流程入门指南
青枫
1月19日
这份指南将带你从零开始，把你的 Docker 镜像托管到 GitHub Container Registry (GHCR)。
第一步：在 GitHub 上生成访问令牌 (PAT)
GitHub 不允许直接使用你的登录密码来通过 Docker 客户端登录，必须使用 Personal Access Token (Classic)。
- 登录 GitHub，点击右上角头像 -> Settings。
- 在左侧菜单最下方，点击 Developer settings。
- 选择 Personal access tokens -> Tokens (classic)。
- 点击 Generate new token -> Generate new token (classic)。
- Note: 写个名字，比如
Docker-GHCR-Token。 - Expiration: 建议选 90 天或更久（过期后需重新生成并登录）。
勾选权限（非常重要）：
write:packages(上传镜像)read:packages(下载镜像)delete:packages(如果你需要删除镜像)- 注意：勾选
write:packages时会自动勾选repo权限，这是正常的。
- 点击最下方的 Generate token。
- 【核心提醒】： 立刻复制并保存这个 Token！一旦刷新页面你就再也看不见它了。
第二步：在本地终端登录 GHCR
打开终端（Terminal 或 PowerShell），执行以下命令：
# 替换你的 GitHub 用户名为小写
export GH_USER="你的GitHub用户名"
export GH_PAT="你刚才复制的Token"
# 执行登录
echo $GH_PAT | docker login ghcr.io -u $GH_USER --password-stdin 如果看到 Login Succeeded，说明第一关过了。
第三步：命名、构建与打标签
GHCR 的镜像命名规则非常严格，格式必须是：ghcr.io/用户名/镜像名:版本号
注意：用户名和镜像名必须全部小写！
假设你的 GitHub 用户名是 stonework，项目叫 my-web-app。
情况 A：直接从 Dockerfile 构建
docker build -t ghcr.io/stonework/my-web-app:v1.0 .情况 B：给已有镜像重命名
如果你本地已经有一个叫 art-design 的镜像了：
docker tag art-design:latest ghcr.io/stonework/my-web-app:v1.0第四步：推送镜像到 GitHub
这是见证奇迹的时刻：
docker push ghcr.io/stonework/my-web-app:v1.0第五步：在 GitHub 网页上管理镜像
- 打开你的 GitHub 主页 (
github.com/你的用户名)。 - 点击顶部导航栏的 Packages。
- 你会看到刚刚上传的
my-web-app。 - 默认是私有的 (Private)：只有你自己能看到。
修改设置（可选）：
- 点击镜像进入详情。
- 点击右侧的 Package settings。
在页面最下方，你可以：
- Change visibility：把镜像设为 Public（公开）。
- Link Repository：把这个镜像和你的某个代码仓库关联起来（关联后，仓库首页右侧会显示镜像入口）。
第六步：在其他机器上下载（拉取）镜像
在你的服务器或其他电脑上，你同样需要先执行 第二步 的登录操作，然后运行：
docker pull ghcr.io/stonework/my-web-app:v1.0进阶：如何彻底实现“一劳永逸”？
如果你觉得手动输入命令太累，GHCR 最强大的地方在于配合 GitHub Actions。
你可以写一个简单的自动化脚本（.github/workflows/docker-publish.yml），实现： 只要你往 GitHub 提交代码，它就自动帮你构建镜像、打版本号并推送到 GHCR。
避坑小贴士：
- 大小写敏感 ：
GHCR.io/User/Image会报错，必须全小写ghcr.io/user/image。 - Token 丢失 ：如果忘了保存 Token，只能重新生成一个并重新
docker login。 - 配额限制 ：GHCR 个人版有 500MB 的免费存储额度。对于一般的 Next.js 项目（压缩后通常很小），完全够用。如果镜像特别巨大，注意清理旧版本。