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 DeployScope选择你的个人账户或团队必须与你的项目所在的组织一致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 CLInpminstall-gvercel登录Vercelvercel login进入你的项目目录链接到Vercel项目vercellink按照提示选择你的账户和项目打开生成的.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中获取的组织/个人IDVERCEL_PROJECT_ID你在2.3中获取的项目ID2.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_USERNAMEDocker Hub用户名这是你的Docker Hub账户的用户名不是邮箱地址。获取步骤登录Docker Hubhttps://hub.docker.com点击右上角的头像你的用户名会显示在下拉菜单的顶部复制该用户名3.2 获取 DOCKER_TOKENDocker Hub访问令牌强烈建议使用访问令牌代替账户密码因为令牌可以限制权限并且可以随时撤销。获取步骤直接访问Docker Hub安全设置页面https://hub.docker.com/settings/security在Access Tokens部分点击New Access Token按钮在New Access Token弹窗中Token description输入一个有意义的名称如GitHub Actions - Image PushAccess 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-name:Login to GitHub Container Registryuses:docker/login-actionv4with:registry:ghcr.iousername:${{github.actor}}password:${{secrets.GITHUB_TOKEN}}构建并推送镜像时镜像名称格式为ghcr.io/你的GitHub用户名/镜像名称:标签四、完整工作流文件示例4.1 前端项目自动部署到Vercelname:Frontend CI/CDon:push:branches:[main]pull_request:branches:[main]jobs:build-and-deploy:runs-on:ubuntu-lateststeps:-name:Checkout codeuses:actions/checkoutv4-name:Setup Node.jsuses:actions/setup-nodev4with:node-version:20cache: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/mainuses:amondnet/vercel-actionv20with:vercel-token:${{secrets.VERCEL_TOKEN}}vercel-org-id:${{secrets.VERCEL_ORG_ID}}vercel-project-id:${{secrets.VERCEL_PROJECT_ID}}vercel-args:--prod4.2 后端项目自动构建并推送Docker镜像name:Backend CI/CDon:push:branches:[main]jobs:build-and-push:runs-on:ubuntu-lateststeps:-name:Checkout codeuses:actions/checkoutv4-name:Setup Node.jsuses:actions/setup-nodev4with:node-version:20cache: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-actionv4with:username:${{secrets.DOCKER_USERNAME}}password:${{secrets.DOCKER_TOKEN}}-name:Build and push Docker imageuses:docker/build-push-actionv5with:context:.push:truetags:${{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