超详细 GitHub Actions 自动发布部署教程

蜡台2026-09-09 12:01

超详细 GitHub Actions 自动发布部署教程

在日常开发中，项目迭代完成后的打包、上传、部署工作往往重复且繁琐：每次更新代码都需要本地打包、登录服务器、替换文件、重启服务，不仅浪费时间，还容易因人为操作失误导致部署失败。

而 GitHub Actions 完美解决了这个痛点，作为 GitHub 官方免费的 CI/CD 工具，无需额外搭建服务器、无需第三方平台，仅通过简单的配置文件，就能实现 代码提交自动触发构建、打包、测试、部署上线 的全自动化流程。

一、什么是 GitHub Actions？

GitHub Actions 是 GitHub 内置的持续集成/持续部署（CI/CD）服务，核心作用是 监听仓库代码变动，自动执行自定义工作流，适配前端、后端、静态网站、服务端项目等几乎所有开发场景。

1. 核心术语

  • Workflow（工作流） ：完整的自动化任务流程，一个仓库可配置多个工作流，文件存放于仓库 .github/workflows/ 目录下，后缀为 .yml。

  • Event（触发事件） ：触发工作流的条件，最常用的是 push（代码推送）、pull_request（合并请求）。

  • Job（任务）：工作流中的独立执行单元，一个工作流可包含多个任务，默认并行执行。

  • Step（步骤）：任务中的具体执行步骤，可执行命令、调用官方插件、自定义脚本。

  • Action（动作）：可复用的自动化脚本（官方/开源社区提供），简化配置，无需手写复杂命令。

2. 优势亮点

  • 完全免费：公开仓库无使用限制，私有仓库免费额度足够个人/小型团队使用；

  • 开箱即用：内置大量官方 Action 插件，支持打包、部署、SSH、OSS 上传等场景；

  • 跨平台：支持 Windows、Linux、MacOS 运行环境；

  • 轻量高效：无需搭建 Jenkins、GitLab CI 等专属服务，零运维成本。

二、前置准备工作

在配置自动化部署前，只需准备2个基础条件

  1. 已有 GitHub 仓库，项目代码已上传（前端Vue/React、后端Node、静态网页等均可）；

  2. 部署目标资源：服务器（云服务器/轻量应用服务器）、GitHub Pages、阿里云OSS、腾讯云COS 等（本文以 服务器SSH部署 通用场景为例）；

  3. 服务器已开启 SSH 登录权限，可正常远程连接。

三、从零配置 GitHub Actions 自动部署

我们以 前端项目（Vue/React）提交代码→自动打包→自动上传服务器部署 为例，手把手完成完整配置，其他项目（后端、静态站）可通用适配。

步骤1：创建工作流配置文件

在你的项目根目录，新建文件夹层级：.github/workflows/，并在目录下新建配置文件，命名为 deploy.yml（文件名自定义，后缀必须 yml）。

重点：目录名称.github/workflows必须完全一致，否则 GitHub 无法识别工作流。

步骤2：完整配置文件详解

下面是通用的前端自动部署配置，包含「代码拉取-环境安装-依赖下载-项目打包-服务器部署」全流程：

yaml 复制代码 
# 工作流名称，GitHub 后台展示的任务名称
name: Auto Deploy Project

# 触发条件：main分支推送代码、合并代码时触发
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# 执行任务
jobs:
  # 构建打包任务
  build-and-deploy:
    # 运行环境：最新Ubuntu系统
    runs-on: ubuntu-latest

    # 执行步骤
    steps:
      # 1. 拉取当前仓库代码
      - name: Checkout Code
        uses: actions/checkout@v4

      # 2. 安装Node.js环境（适配前端项目）
      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18 # 适配你的项目Node版本
          cache: 'npm' # 缓存依赖，提升下次构建速度

      # 3. 安装项目依赖
      - name: Install Dependencies
        run: npm install

      # 4. 项目打包（根据你的项目修改打包命令）
      - name: Build Project
        run: npm run build

      # 5. 部署到远程服务器（核心步骤）
      - name: Deploy to Server
        uses: easingthemes/ssh-deploy@v2
        env:
          # 服务器SSH密钥（后续配置GitHub密钥）
          SSH_PRIVATE_KEY: ${{ secrets.SSH_KEY }}
          # 服务器IP、端口、账号
          REMOTE_HOST: ${{ secrets.SERVER_HOST }}
          REMOTE_USER: ${{ secrets.SERVER_USER }}
          REMOTE_PORT: ${{ secrets.SERVER_PORT }}
          # 本地打包后的文件目录（前端默认dist）
          SOURCE: dist/
          # 服务器部署目录（替换为你的项目部署路径）
          TARGET: /usr/local/nginx/html/project
          # 部署前清空服务器旧文件（避免残留缓存）
          ARGS: "-rltgoDzvO --delete"

步骤3：配置 GitHub 仓库密钥

配置文件中 secrets.xxx 是加密环境变量，绝对不能直接写在配置文件中，需要在 GitHub 仓库后台手动配置：

  1. 打开你的 GitHub 项目仓库，点击顶部 Settings；

  2. 左侧菜单栏找到 Secrets and variables → Actions；

  3. 点击New repository secret，依次添加4个密钥：

密钥名称（Name） 密钥值（Secret）
SSH_KEY 本地SSH私钥（~/.ssh/id_rsa 完整内容）
SERVER_HOST 服务器公网IP地址
SERVER_USER 服务器登录账号（如 root）
SERVER_PORT 服务器SSH端口（默认22）

⚠️ 注意：私钥无需密码，确保服务器已添加本地公钥到 ~/.ssh/authorized_keys，保证免密登录。

步骤4：提交配置，触发自动部署

将新建的 .github/workflows/deploy.yml 文件提交并推送到 GitHub 远程仓库：

bash 复制代码 
git add .
git commit -m "feat: 新增github actions自动部署配置"
git push

推送完成后，仓库顶部点击 Actions 标签，即可看到正在执行的工作流任务，点击进入可查看实时日志。

当任务全部显示绿色 ✅ success，代表部署完成，打开项目域名即可看到最新代码效果。

四、常用场景适配修改

1. React 项目适配

React 项目打包命令、打包目录和 Vue 一致，无需修改配置，直接复用即可。

2. 后端 Node 项目适配

删除前端打包步骤，新增项目启动命令，示例修改：

yaml 复制代码 
# 替换打包步骤
- name: Build & Start Server
  run: |
    npm install
    pm2 restart server || pm2 start app.js --name server

3. GitHub Pages 自动部署

GitHub Pages 是 GitHub 免费提供的静态页面托管服务，无需服务器、无需域名，适合 Vue、React、H5、文档站等静态项目托管。下面给出 零报错、可直接复用 的 GitHub Actions 自动部署 Pages 完整方案，解决「POST请求报错、页面空白、部署不更新」等常见问题。

第一步：仓库基础配置

  1. 进入仓库 Settings → Pages；

  2. Build and deployment 选择：GitHub Actions（必须选择，否则自动部署不生效）；

  3. 无需手动选择分支和目录，交由工作流自动配置覆盖。

第二步：新增 GitHub Pages 专属工作流文件

在 .github/workflows/ 目录新建文件 pages-deploy.yml，专门用于静态页面自动部署，和服务器部署配置互不冲突，完整代码如下

yaml 复制代码 
# GitHub Pages 静态项目自动部署 + 钉钉通知
name: Deploy GitHub Pages

# 触发条件：main分支推送、合并代码触发
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# 权限配置：必须开启页面读写权限，否则部署失败
permissions:
  contents: read
  pages: write
  id-token: write

# 并发限制：避免多次部署冲突
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # 构建静态资源
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      # 适配前端项目打包
      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: 'npm'

      - name: Install Dependencies
        run: npm install

      - name: Build Static Page
        run: npm run build

      # 上传打包产物为部署资源
      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist # 根据你的项目打包目录修改

  # 部署到 GitHub Pages
  deploy:
    # 依赖构建任务完成
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

      # 钉钉部署成功通知（原生POST请求，解决 43002 需要POST请求报错）
      - name: DingTalk Success Notify
        if: success()
        uses: crazy-max/dingtalk-action@v2
        with:
          webhook: ${{ secrets.DINGTALK_WEBHOOK }}
          msgtype: markdown
          content: |
            ### ✅ GitHub Pages 部署成功
            - 部署分支：${{ github.ref_name }}
            - 提交人：${{ github.actor }}
            - 访问地址：[点击访问](${{ steps.deployment.outputs.page_url }})

      - name: DingTalk Fail Notify
        if: failure()
        uses: crazy-max/dingtalk-action@v2
        with:
          webhook: ${{ secrets.DINGTALK_WEBHOOK }}
          msgtype: markdown
          content: |
            ### ❌ GitHub Pages 部署失败
            - 部署分支：${{ github.ref_name }}
            - 提交人：${{ github.actor }}
            - 请及时查看 Actions 日志排查问题
第三步：关键配置说明

  • 修复 43002 需要POST请求报错 ：替换老旧钉钉Action，使用官方兼容POST请求的 crazy-max/dingtalk-action@v2，彻底解决钉钉机器人仅支持POST、旧插件GET请求报错问题；

  • 权限配置必加 ：新增 permissions 权限配置，是新版 GitHub Pages 部署强制要求，缺失会直接部署失败；

  • 目录适配 ：Vue/React 默认打包目录为 dist，Nuxt/Vite 项目可根据实际输出目录修改 path 参数。

第四步：生效测试

提交并推送配置文件，触发工作流：git push，等待任务绿色成功后，即可通过日志中的页面地址访问项目，同时钉钉群正常接收部署通知。

GitHub Pages 专属避坑点

  • 页面空白：检查打包资源路径，静态项目需配置 publicPath: ./ 相对路径，避免绝对路径资源加载失败；

  • 部署成功但页面无更新：开启并发限制、清理浏览器缓存，或手动重新执行工作流；

  • 权限报错：必须完整配置文档中的 permissions 权限字段，新版 GH Pages 已废弃旧权限规则。

无需服务器，直接使用官方 pages-deploy 插件，可实现静态项目免费托管部署。

五、常见报错与避坑指南

1. 部署失败：SSH 连接超时/拒绝连接

✅ 原因：服务器防火墙未开放SSH端口、密钥配置错误、服务器未添加公钥

✅ 解决：检查服务器安全组放行22端口、重新复制完整私钥、确认本地公钥已录入服务器。

2. 打包失败：依赖安装报错

✅ 原因：Node版本不匹配、项目依赖兼容问题

✅ 解决：修改配置中 node-version 为项目本地一致版本，锁定依赖版本。

3. 部署后页面无更新

✅ 原因：服务器旧文件缓存、打包目录配置错误

✅ 解决：配置中保留 ARGS: "-rltgoDzvO --delete" 清空旧文件，核对 SOURCE 打包目录。

4. 工作流不触发

✅ 原因：分支不匹配、配置文件目录错误

✅ 解决：确保推送分支为 main，目录严格为 .github/workflows。

六、进阶优化技巧

  1. 开启依赖缓存 ：配置中 cache: 'npm' 可缓存node_modules，大幅缩短构建时间；

  2. 指定触发分支：仅配置主干分支触发部署，避免开发分支误部署；

  3. 添加部署通知：对接钉钉/企业微信机器人，部署成功/失败实时推送消息提醒

  4. 多环境部署：区分测试环境、生产环境，配置不同部署目录和触发分支。

1、钉钉机器人部署通知完整配置

通过配置钉钉机器人，可实现 GitHub Actions 部署 成功/失败/取消 状态实时推送，无需手动查看仓库日志，全程监控部署状态，适配所有部署场景。

第一步：创建钉钉自定义机器人

  1. Open DingTalk and enter the group chat where you want to receive notifications;

  2. Click Group Settings → Smart Group Assistant → Add Robot → select "Custom Robot";

  3. Set the robot name (e.g., "Project Deployment Notification"), enable Custom Keywords , and enter the keyword: GitHub (required, otherwise notifications will fail);

  4. After creation, copy the robot's Webhook URL , in the format: https://oapi.dingtalk.com/robot/send?access_token=xxxxxx.#### 第二步：配置 GitHub 私密密钥

和服务器密钥配置方式一致，在仓库 Settings → Secrets and variables → Actions 中，新增1个密钥：

  • 密钥名称：DINGTALK_WEBHOOK

  • 密钥值：钉钉机器人完整的 Webhook 地址

第三步：完整改造工作流配置文件

基于前文的部署配置，新增钉钉通知步骤，支持部署成功、部署失败、任务取消 三种状态精准推送，以下是可直接复用的完整 deploy.yml 配置：

yaml 复制代码 
# 工作流名称，GitHub 后台展示的任务名称
name: Auto Deploy Project

# 触发条件：main分支推送代码、合并代码时触发
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

# 执行任务
jobs:
  # 构建打包任务
  build-and-deploy:
    # 运行环境：最新Ubuntu系统
    runs-on: ubuntu-latest

    # 执行步骤
    steps:
      # 1. 拉取当前仓库代码
      - name: Checkout Code
        uses: actions/checkout@v4

      # 2. 安装Node.js环境（适配前端项目）
      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18 # 适配你的项目Node版本
          cache: 'npm' # 缓存依赖，提升下次构建速度

      # 3. 安装项目依赖
      - name: Install Dependencies
        run: npm install

      # 4. 项目打包（根据你的项目修改打包命令）
      - name: Build Project
        run: npm run build

      # 5. 部署到远程服务器（核心步骤）
      - name: Deploy to Server
        uses: easingthemes/ssh-deploy@v2
        env:
          # 服务器SSH密钥（后续配置GitHub密钥）
          SSH_PRIVATE_KEY: ${{ secrets.SSH_KEY }}
          # 服务器IP、端口、账号
          REMOTE_HOST: ${{ secrets.SERVER_HOST }}
          REMOTE_USER: ${{ secrets.SERVER_USER }}
          REMOTE_PORT: ${{ secrets.SERVER_PORT }}
          # 本地打包后的文件目录（前端默认dist）
          SOURCE: dist/
          # 服务器部署目录（替换为你的项目部署路径）
          TARGET: /usr/local/nginx/html/project
          # 部署前清空服务器旧文件（避免残留缓存）
          ARGS: "-rltgoDzvO --delete"

      # 6. 钉钉部署成功通知
      - name: DingTalk Deploy Success
        if: success()
        uses: zkxiaoming/dingtalk-action@v1
        with:
          webhook: ${{ secrets.DINGTALK_WEBHOOK }}
          title: '✅ 项目部署成功'
          message: |
            【GitHub Actions 自动部署通知】
            项目分支：${{ github.ref_name }}
            提交人：${{ github.actor }}
            提交信息：${{ github.event.head_commit.message }}
            部署状态：部署完成，服务正常上线

      # 7. 钉钉部署失败通知
      - name: DingTalk Deploy Failed
        if: failure()
        uses: zkxiaoming/dingtalk-action@v1
        with:
          webhook: ${{ secrets.DINGTALK_WEBHOOK }}
          title: '❌ 项目部署失败'
          message: |
            【GitHub Actions 自动部署通知】
            项目分支：${{ github.ref_name }}
            提交人：${{ github.actor }}
            提交信息：${{ github.event.head_commit.message }}
            部署状态：部署异常，请及时排查日志修复

      # 8. 钉钉任务取消通知
      - name: DingTalk Deploy Cancelled
        if: cancelled()
        uses: zkxiaoming/dingtalk-action@v1
        with:
          webhook: ${{ secrets.DINGTALK_WEBHOOK }}
          title: '⚠️ 项目部署取消'
          message: |
            【GitHub Actions 自动部署通知】
            项目分支：${{ github.ref_name }}
            提交人：${{ github.actor }}
            部署状态：部署任务被手动取消
第四步：测试生效

修改代码并执行 git push 推送代码，部署流程结束后，钉钉群会自动接收对应状态的通知消息，无需人工值守查看部署日志。

常见问题避坑

  • 收不到消息：检查钉钉机器人自定义关键词 是否包含 GitHub，核对 Webhook 地址是否完整无误；

  • 通知不精准：确认 if: success() / failure() / cancelled() 条件不遗漏，三个状态步骤缺一不可；

  • 权限报错：无需额外权限，仅需正确配置 GitHub 仓库私密密钥即可正常使用。

七、总结

GitHub Actions 作为零成本、零运维的 CI/CD 工具，一次配置、永久省心，彻底告别手动部署的低效和失误。

核心流程总结：创建工作流配置文件 → 配置仓库私密密钥 → 提交代码触发自动构建部署，适配几乎所有前后端项目部署场景，是个人开发、小型团队的最优自动化部署方案。

配置完成后，后续所有代码更新，只需 git push 一行命令，即可自动完成全流程部署，极大提升开发迭代效率！

相关推荐
11路没有终点2 小时前
CI/CD 集成：GitHub Actions
ci/cd·github
右耳朵猫AI3 小时前
Github周刊2026W36 | Archify架构图生成、科研Agent技能库、VoiceStudio本地语音、MiniMind训练6400万参数
github
DeepAgent3 小时前
AI Agent 开发实战（13）：GitHub 开源
开源·github·agent
Jul1en_4 小时前
Matt 与 Uncle Bob 的播客访谈有感
开发语言·经验分享·笔记·ai·开源·github·ai编程
hrx-@@5 小时前
DSH 插件开发到上架：完整实操手册
人工智能·语言模型·开源·github
一条泥憨鱼5 小时前
【从0开始学习计算机网络】| 邮件协议入门：SMTP、POP3、IMAP
linux·运维·计算机网络·github
lpfasd1237 小时前
2026年第36周GitHub趋势周报：Agent技能化、MCP工具化与AI工程化加速
人工智能·github
OpenTiny社区19 小时前
【直播分享】GenUI SDK 技术公开课第二讲 | GenuiChat 核心配置深度解析
前端·github
dong_junshuai19 小时前
每天一个开源项目#93 HyperFrames：4.69万星的 HTML 视频渲染框架
开源·html·github
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点03历年考研数学一、数学二、数学三真题试卷及答案PDF04蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接052026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新07如何新建文件夹？ 电脑新建文件夹的4种方法08ZCode 周末送额度活动开启：3 亿 Token 免费领取09Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费10AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路