GitHub Actions 完整 Token/Secret 配置详解（Vercel + Docker 2026最新版）

GitHub Actions 完整 Token/Secret 配置详解（Vercel + Docker 2026最新版）

本文将手把手教你获取并配置GitHub Actions自动化部署所需的所有凭证，包括Vercel部署的3个关键secret和Docker镜像推送的2个关键secret，每个步骤都提供直接访问链接和精确操作指引，确保零错误配置。

一、GitHub Secrets 通用添加步骤（所有凭证通用）

所有需要在GitHub Actions中使用的敏感信息都必须存储在仓库级别的Secrets中，绝对不能直接写在工作流文件里。

详细操作步骤

1. 打开你的GitHub仓库主页
2. 点击顶部导航栏的Settings（设置）标签
3. 在左侧菜单栏的Security（安全）部分，找到并点击Secrets and variables→Actions
4. 点击右上角的New repository secret（新建仓库密钥）按钮
5. 在Name字段输入密钥名称（如VERCEL_TOKEN）
6. 在Secret字段输入密钥的值
7. 点击Add secret（添加密钥）按钮完成添加

重要规则：

• 密钥名称只能包含字母、数字和下划线，不能以数字或GITHUB_开头
• 密钥名称不区分大小写
• 密钥添加后无法查看，只能重新生成并替换
• 密钥在工作流日志中会被自动屏蔽为***

二、Vercel 部署所需 Secret 配置

使用GitHub Actions部署到Vercel需要3个关键凭证：VERCEL_TOKEN、VERCEL_ORG_ID和VERCEL_PROJECT_ID。

2.1 获取 VERCEL_TOKEN（访问令牌）

这是Vercel API的身份验证凭证，用于授权GitHub Actions操作你的Vercel项目。

获取步骤：

1. 直接访问Vercel令牌创建页面：https://vercel.com/account/tokens
2. 登录你的Vercel账号
3. 在"Create New Token"部分：
   • Token name：输入一个有意义的名称，如GitHub Actions - Production Deploy
   • Scope：选择你的个人账户或团队（必须与你的项目所在的组织一致）
   • Expiration：建议选择"Never"（永不过期）或设置一个较长的时间（如1年）
4. 点击Create Token按钮
5. 立即复制生成的令牌（这是唯一一次显示机会，关闭页面后无法再次查看）

2.2 获取 VERCEL_ORG_ID（组织/个人ID）

这是你的Vercel个人账户或团队的唯一标识符。

方法一：通过网页控制台获取（推荐）

1. 直接访问Vercel账户设置页面：https://vercel.com/account/general
2. 向下滚动页面，找到Your ID（个人账户）或Team ID（团队账户）字段
3. 复制该ID值

方法二：通过Vercel CLI获取

1. 安装Vercel CLI：

   npminstall-gvercel

2. 登录Vercel：

   vercel login

3. 进入你的项目目录，链接到Vercel项目：

   vercellink

4. 按照提示选择你的账户和项目
5. 打开生成的.vercel/project.json文件，复制orgId字段的值

2.3 获取 VERCEL_PROJECT_ID（项目ID）

这是你的Vercel项目的唯一标识符。

方法一：通过网页控制台获取（推荐）

1. 打开Vercel控制台：https://vercel.com/dashboard
2. 点击你要部署的项目
3. 点击顶部导航栏的Settings（设置）标签
4. 在General（常规）页面向下滚动，找到Project ID字段
5. 复制该ID值

方法二：通过Vercel CLI获取

• 按照上面"方法二"的步骤操作后，打开.vercel/project.json文件，复制projectId字段的值

2.4 添加到GitHub Secrets

按照第一部分的通用步骤，将以下三个secret添加到你的GitHub仓库：

• VERCEL_TOKEN：你在2.1中获取的访问令牌
• VERCEL_ORG_ID：你在2.2中获取的组织/个人ID
• VERCEL_PROJECT_ID：你在2.3中获取的项目ID

2.5 重要注意事项

1. 关闭Vercel自动部署：如果你想完全由GitHub Actions控制部署流程，需要在Vercel项目设置中关闭自动部署：

   • 进入Vercel项目 → Settings → Build & Deployment
   • 找到"Ignore Build Step"选项，选择"Don’t build anything"
   • 这样当你推送代码到GitHub时，Vercel不会自动构建和部署，只有GitHub Actions会触发部署

2. 常见错误：Project not found

   • 原因：VERCEL_ORG_ID和VERCEL_PROJECT_ID不匹配
   • 解决方法：确保两个ID都来自同一个账户/团队和同一个项目
   • 检查：在Vercel项目设置页面，同时查看Team ID和Project ID，确保复制正确

三、Docker 镜像推送所需 Secret 配置

使用GitHub Actions构建并推送Docker镜像到Docker Hub需要2个关键凭证：DOCKER_USERNAME和DOCKER_TOKEN。

3.1 获取 DOCKER_USERNAME（Docker Hub用户名）

这是你的Docker Hub账户的用户名（不是邮箱地址）。

获取步骤：

1. 登录Docker Hub：https://hub.docker.com
2. 点击右上角的头像，你的用户名会显示在下拉菜单的顶部
3. 复制该用户名

3.2 获取 DOCKER_TOKEN（Docker Hub访问令牌）

强烈建议使用访问令牌代替账户密码，因为令牌可以限制权限，并且可以随时撤销。

获取步骤：

1. 直接访问Docker Hub安全设置页面：https://hub.docker.com/settings/security
2. 在"Access Tokens"部分，点击New Access Token按钮
3. 在"New Access Token"弹窗中：
   • Token description：输入一个有意义的名称，如GitHub Actions - Image Push
   • Access permissions：选择"Read, write, delete"（读写删除权限）或根据需要选择更严格的权限
4. 点击Generate按钮
5. 立即复制生成的令牌（这是唯一一次显示机会，关闭弹窗后无法再次查看）

3.3 添加到GitHub Secrets

按照第一部分的通用步骤，将以下两个secret添加到你的GitHub仓库：

• DOCKER_USERNAME：你在3.1中获取的Docker Hub用户名
• DOCKER_TOKEN：你在3.2中获取的Docker Hub访问令牌

3.4 扩展：GitHub Container Registry (GHCR) 配置

如果你不想使用Docker Hub，也可以使用GitHub自带的容器注册表GHCR，它不需要额外的token，直接使用GitHub自动生成的GITHUB_TOKEN即可。

配置步骤：

1. 不需要添加任何额外的secret
2. 在你的GitHub Actions工作流中使用以下配置登录GHCR：

   -name:Login to GitHub Container Registryuses:docker/login-action@v4with:registry:ghcr.iousername:${{github.actor}}password:${{secrets.GITHUB_TOKEN}}

3. 构建并推送镜像时，镜像名称格式为：ghcr.io/你的GitHub用户名/镜像名称:标签

四、完整工作流文件示例

4.1 前端项目自动部署到Vercel

name:Frontend CI/CDon:push:branches:[main]pull_request:branches:[main]jobs:build-and-deploy:runs-on:ubuntu-lateststeps:-name:Checkout codeuses:actions/checkout@v4-name:Setup Node.jsuses:actions/setup-node@v4with:node-version:'20'cache:'npm'-name:Install dependenciesrun:npm ci-name:Run ESLintrun:npm run lint-name:Run testsrun:npm run test-name:Build applicationrun:npm run build-name:Deploy to Vercelif:github.ref == 'refs/heads/main'uses:amondnet/vercel-action@v20with:vercel-token:${{secrets.VERCEL_TOKEN}}vercel-org-id:${{secrets.VERCEL_ORG_ID}}vercel-project-id:${{secrets.VERCEL_PROJECT_ID}}vercel-args:'--prod'

4.2 后端项目自动构建并推送Docker镜像

name:Backend CI/CDon:push:branches:[main]jobs:build-and-push:runs-on:ubuntu-lateststeps:-name:Checkout codeuses:actions/checkout@v4-name:Setup Node.jsuses:actions/setup-node@v4with:node-version:'20'cache:'npm'-name:Install dependenciesrun:npm ci-name:Run ESLintrun:npm run lint-name:Run testsrun:npm run test-name:Login to Docker Hubuses:docker/login-action@v4with:username:${{secrets.DOCKER_USERNAME}}password:${{secrets.DOCKER_TOKEN}}-name:Build and push Docker imageuses:docker/build-push-action@v5with:context:.push:truetags:${{secrets.DOCKER_USERNAME}}/my-backend:latest

五、最佳实践与安全建议

1. 最小权限原则：为每个token分配最小必要的权限
2. 定期轮换token：建议每6-12个月轮换一次所有的访问令牌
3. 不要共享token：每个服务或集成应该使用单独的token
4. 使用环境级别的secret：如果有多个部署环境（如staging、production），可以使用GitHub的环境功能来隔离不同环境的secret
5. 不要在代码中硬编码任何敏感信息：所有敏感信息都应该存储在GitHub Secrets或环境变量中
6. 审查工作流文件：在合并包含工作流文件的PR时，仔细审查是否有泄露secret的风险

六、常见问题排查

1. 问题：Vercel部署失败，提示"Invalid token"

   • 解决方法：重新生成VERCEL_TOKEN并更新到GitHub Secrets

2. 问题：Docker镜像推送失败，提示"unauthorized: incorrect username or password"

   • 解决方法：检查DOCKER_USERNAME和DOCKER_TOKEN是否正确，确保DOCKER_TOKEN有足够的权限

3. 问题：GitHub Actions无法访问secret

   • 解决方法：确保secret是添加在正确的仓库中，并且工作流文件中引用的secret名称与添加的名称完全一致

4. 问题：secret在工作流中显示为空

   • 解决方法：确保secret是添加在"Repository secrets"部分，而不是"Environment secrets"或"Organization secrets"（除非你明确使用了环境或组织级别的secret）