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

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

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

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

详细操作步骤

打开你的GitHub仓库主页
点击顶部导航栏的 Settings（设置）标签
在左侧菜单栏的 Security （安全）部分，找到并点击 Secrets and variables → Actions
点击右上角的 New repository secret（新建仓库密钥）按钮
在 Name 字段输入密钥名称（如VERCEL_TOKEN）
在 Secret 字段输入密钥的值
点击 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项目。

获取步骤：

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

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

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

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

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

方法二：通过Vercel CLI获取

安装Vercel CLI：
bash 复制代码
```
npm install -g vercel
```
登录Vercel：
bash 复制代码
```
vercel login
```
进入你的项目目录，链接到Vercel项目：
bash 复制代码
```
vercel link
```
按照提示选择你的账户和项目
打开生成的.vercel/project.json文件，复制orgId字段的值

2.3 获取 VERCEL_PROJECT_ID（项目ID）

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

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

打开Vercel控制台：https://vercel.com/dashboard
点击你要部署的项目
点击顶部导航栏的 Settings（设置）标签
在 General （常规）页面向下滚动，找到 Project ID 字段
复制该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 重要注意事项

关闭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账户的用户名（不是邮箱地址）。

获取步骤：

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

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

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

获取步骤：

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

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即可。

配置步骤：

不需要添加任何额外的secret

在你的GitHub Actions工作流中使用以下配置登录GHCR：

yaml 复制代码

- name: Login to GitHub Container Registry
  uses: docker/login-action@v4
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

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

四、完整工作流文件示例

4.1 前端项目自动部署到Vercel

yaml 复制代码

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镜像

yaml 复制代码

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

五、最佳实践与安全建议

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

六、常见问题排查

问题：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）