GitHub Actions 完整 Token/Secret 配置详解（Vercel + Docker 2026最新版）
本文将手把手教你获取并配置GitHub Actions自动化部署所需的所有凭证，包括Vercel部署的3个关键secret和Docker镜像推送的2个关键secret，每个步骤都提供直接访问链接和精确操作指引，确保零错误配置。
一、GitHub Secrets 通用添加步骤（所有凭证通用）
所有需要在GitHub Actions中使用的敏感信息都必须存储在仓库级别的Secrets中，绝对不能直接写在工作流文件里。
详细操作步骤
重要规则：
- 密钥名称只能包含字母、数字和下划线，不能以数字或GITHUB_开头
- 密钥名称不区分大小写
- 密钥添加后无法查看，只能重新生成并替换
- 密钥在工作流日志中会被自动屏蔽为***
二、Vercel 部署所需 Secret 配置
使用GitHub Actions部署到Vercel需要3个关键凭证：VERCEL_TOKEN、VERCEL_ORG_ID和VERCEL_PROJECT_ID。
2.1 获取 VERCEL_TOKEN（访问令牌）
这是Vercel API的身份验证凭证，用于授权GitHub Actions操作你的Vercel项目。
获取步骤：
- Token name：输入一个有意义的名称，如GitHub Actions – Production Deploy
- Scope：选择你的个人账户或团队（必须与你的项目所在的组织一致）
- Expiration：建议选择"Never"（永不过期）或设置一个较长的时间（如1年）
2.2 获取 VERCEL_ORG_ID（组织/个人ID）
这是你的Vercel个人账户或团队的唯一标识符。
方法一：通过网页控制台获取（推荐）
方法二：通过Vercel CLI获取
2.3 获取 VERCEL_PROJECT_ID（项目ID）
这是你的Vercel项目的唯一标识符。
方法一：通过网页控制台获取（推荐）
方法二：通过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 重要注意事项
关闭Vercel自动部署：如果你想完全由GitHub Actions控制部署流程，需要在Vercel项目设置中关闭自动部署：
- 进入Vercel项目 → Settings → Build & Deployment
- 找到"Ignore Build Step"选项，选择"Don’t build anything"
- 这样当你推送代码到GitHub时，Vercel不会自动构建和部署，只有GitHub Actions会触发部署
常见错误：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账户的用户名（不是邮箱地址）。
获取步骤：
3.2 获取 DOCKER_TOKEN（Docker Hub访问令牌）
强烈建议使用访问令牌代替账户密码，因为令牌可以限制权限，并且可以随时撤销。
获取步骤：
- Token description：输入一个有意义的名称，如GitHub Actions – Image Push
- Access permissions：选择"Read, write, delete"（读写删除权限）或根据需要选择更严格的权限
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即可。
配置步骤：
uses: docker/login–action@v4
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
四、完整工作流文件示例
4.1 前端项目自动部署到Vercel
name: Frontend CI/CD
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build-and-deploy:
runs-on: ubuntu–latest
steps:
– name: Checkout code
uses: actions/checkout@v4
– name: Setup Node.js
uses: actions/setup–node@v4
with:
node-version: '20'
cache: 'npm'
– name: Install dependencies
run: npm ci
– name: Run ESLint
run: npm run lint
– name: Run tests
run: npm run test
– name: Build application
run: npm run build
– name: Deploy to Vercel
if: github.ref == 'refs/heads/main'
uses: amondnet/vercel–action@v20
with:
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/CD
on:
push:
branches: [ main ]
jobs:
build-and-push:
runs-on: ubuntu–latest
steps:
– name: Checkout code
uses: actions/checkout@v4
– name: Setup Node.js
uses: actions/setup–node@v4
with:
node-version: '20'
cache: 'npm'
– name: Install dependencies
run: npm ci
– name: Run ESLint
run: npm run lint
– name: Run tests
run: npm run test
– name: Login to Docker Hub
uses: docker/login–action@v4
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_TOKEN }}
– name: Build and push Docker image
uses: docker/build–push–action@v5
with:
context: .
push: true
tags: ${{ secrets.DOCKER_USERNAME }}/my–backend:latest
五、最佳实践与安全建议
六、常见问题排查
问题：Vercel部署失败，提示"Invalid token"
- 解决方法：重新生成VERCEL_TOKEN并更新到GitHub Secrets
问题：Docker镜像推送失败，提示"unauthorized: incorrect username or password"
- 解决方法：检查DOCKER_USERNAME和DOCKER_TOKEN是否正确，确保DOCKER_TOKEN有足够的权限
问题：GitHub Actions无法访问secret
- 解决方法：确保secret是添加在正确的仓库中，并且工作流文件中引用的secret名称与添加的名称完全一致
问题：secret在工作流中显示为空
- 解决方法：确保secret是添加在"Repository secrets"部分，而不是"Environment secrets"或"Organization secrets"（除非你明确使用了环境或组织级别的secret）
