GitHub Actions 自动部署 Next.js 项目到 Ubuntu 服务器完整指南

什么是自动部署

在传统部署流程中，每次修改代码后，我们通常需要手动登录服务器，执行 git pull、安装依赖、构建项目以及重启服务。

这种方式不仅效率低，而且容易因为人为操作导致部署错误。

自动部署（Continuous Deployment，持续部署）可以让整个流程自动化：

context-payment.ts

开发者
  |
  | git push
  ↓
GitHub Repository
  |
  | Trigger GitHub Actions
  ↓
GitHub Runner
  |
  | SSH Connect
  ↓
Ubuntu Server
  |
  | execute deploy.sh
  ↓
Next.js Application

当代码提交到 main 分支后，GitHub Actions 会自动连接服务器，并执行部署脚本。

整体架构

一个简单可靠的 Next.js 自动部署架构如下：

context-payment.ts

Host
 ├── GitHub Repository
 │
 ├── GitHub Actions
 │       |
 │       | SSH
 │       ↓
 └── Ubuntu Server
         |
         ├── /var/www/personal-website
         ├── deploy.sh
         ├── npm install
         ├── npm run build
         └── pm2 restart

其中：

GitHub Actions 负责触发部署
SSH Key 负责服务器认证
deploy.sh 负责执行具体部署流程
PM2 负责管理 Node.js 服务

配置服务器 SSH 密钥

首先进入服务器：

context-payment.ts

ssh ubuntu@your-server-ip

生成专用于 GitHub Actions 的密钥：

context-payment.ts

ssh-keygen -t ed25519 -C "github-actions" -f ~/.ssh/github_actions

生成后会得到两个文件：

context-payment.ts

~/.ssh/
 ├── github_actions        # 私钥
 └── github_actions.pub    # 公钥

其中：

私钥保存到 GitHub Secrets
公钥添加到服务器授权列表

添加 SSH 公钥

查看公钥：

context-payment.ts

cat ~/.ssh/github_actions.pub

复制内容，然后添加：

context-payment.ts

cat ~/.ssh/github_actions.pub >> ~/.ssh/authorized_keys

测试：

context-payment.ts

ssh -i ~/.ssh/github_actions localhost

如果可以免密码登录，说明 SSH 配置成功。

配置 GitHub Secrets

进入 GitHub 仓库：

context-payment.ts

Settings
 ↓
Secrets and variables
 ↓
Actions

添加三个 Repository secrets：

context-payment.ts

SERVER_HOST
SERVER_USER
SERVER_SSH_KEY

示例：

context-payment.ts

SERVER_HOST=服务器公网IP
SERVER_USER=ubuntu
SERVER_SSH_KEY=-----BEGIN OPENSSH PRIVATE KEY-----

注意：

SSH_KEY 必须是私钥，不是 .pub 文件。

编写部署脚本 deploy.sh

服务器项目目录：

context-payment.ts

/var/www/personal-website

创建：

context-payment.ts

touch deploy.sh

内容：

context-payment.ts

#!/bin/bash

set -e

cd /var/www/personal-website

echo "Pull latest code"
git pull origin main

echo "Install dependencies"
npm install

echo "Generate Prisma Client"
npx prisma generate

echo "Build Next.js"
npm run build

echo "Restart PM2"
pm2 restart personal-website

 echo "Deploy finished"

增加执行权限：

context-payment.ts

chmod +x deploy.sh

测试：

context-payment.ts

./deploy.sh

创建 GitHub Actions Workflow

项目根目录创建：

context-payment.ts

.github/workflows/deploy.yml

内容：

context-payment.ts

name: Deploy

on:
  push:
    branches:
      - main

  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Deploy Server
        uses: appleboy/ssh-action@v1.2.2
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            cd /var/www/personal-website
            ./deploy.sh

测试自动部署

提交代码：

context-payment.ts

git add .
git commit -m "test deploy"
git push origin main

进入 GitHub：

context-payment.ts

Actions
 ↓
Deploy

可以看到：

context-payment.ts

Queued
 ↓
Running
 ↓
Completed

部署成功后，服务器上的 PM2 会自动重新加载最新代码。

常见问题

SSH Permission denied

错误：

context-payment.ts

Permission denied (publickey)

检查：

GitHub Secret 是否填写私钥
authorized_keys 是否包含公钥
用户名是否正确

deploy.sh 没有权限

错误：

context-payment.ts

Permission denied

解决：

context-payment.ts

chmod +x deploy.sh

PM2 找不到应用

查看：

context-payment.ts

pm2 list

确认名称：

context-payment.ts

pm2 restart personal-website

优化方向

生产环境还可以进一步优化：

使用 npm ci 替代 npm install
build 失败不重启服务
使用 pm2 reload 实现零停机部署
添加部署日志
添加失败通知
使用 Docker 部署

总结

通过 GitHub Actions + SSH + deploy.sh + PM2，我们实现了一套完整的 Next.js 自动部署流程。

以后只需要：

context-payment.ts

git push

服务器即可自动完成代码更新、依赖安装、项目构建以及服务重启。

这就是现代 Web 项目中常见的 CI/CD 工作流。

# Next # Node # Nginx # github-actions # pm2 # ubuntu

GitHub Actions 自动部署 Next.js 项目到 Ubuntu 服务器完整指南

什么是自动部署

在传统部署流程中，每次修改代码后，我们通常需要手动登录服务器，执行 git pull、安装依赖、构建项目以及重启服务。

这种方式不仅效率低，而且容易因为人为操作导致部署错误。

自动部署（Continuous Deployment，持续部署）可以让整个流程自动化：

context-payment.ts

开发者
  |
  | git push
  ↓
GitHub Repository
  |
  | Trigger GitHub Actions
  ↓
GitHub Runner
  |
  | SSH Connect
  ↓
Ubuntu Server
  |
  | execute deploy.sh
  ↓
Next.js Application

当代码提交到 main 分支后，GitHub Actions 会自动连接服务器，并执行部署脚本。

整体架构

一个简单可靠的 Next.js 自动部署架构如下：

context-payment.ts

Host
 ├── GitHub Repository
 │
 ├── GitHub Actions
 │       |
 │       | SSH
 │       ↓
 └── Ubuntu Server
         |
         ├── /var/www/personal-website
         ├── deploy.sh
         ├── npm install
         ├── npm run build
         └── pm2 restart

其中：

GitHub Actions 负责触发部署
SSH Key 负责服务器认证
deploy.sh 负责执行具体部署流程
PM2 负责管理 Node.js 服务

配置服务器 SSH 密钥

首先进入服务器：

context-payment.ts

ssh ubuntu@your-server-ip

生成专用于 GitHub Actions 的密钥：

context-payment.ts

ssh-keygen -t ed25519 -C "github-actions" -f ~/.ssh/github_actions

生成后会得到两个文件：

context-payment.ts

~/.ssh/
 ├── github_actions        # 私钥
 └── github_actions.pub    # 公钥

其中：

私钥保存到 GitHub Secrets
公钥添加到服务器授权列表

添加 SSH 公钥

查看公钥：

context-payment.ts

cat ~/.ssh/github_actions.pub

复制内容，然后添加：

context-payment.ts

cat ~/.ssh/github_actions.pub >> ~/.ssh/authorized_keys

测试：

context-payment.ts

ssh -i ~/.ssh/github_actions localhost

如果可以免密码登录，说明 SSH 配置成功。

配置 GitHub Secrets

进入 GitHub 仓库：

context-payment.ts

Settings
 ↓
Secrets and variables
 ↓
Actions

添加三个 Repository secrets：

context-payment.ts

SERVER_HOST
SERVER_USER
SERVER_SSH_KEY

示例：

context-payment.ts

SERVER_HOST=服务器公网IP
SERVER_USER=ubuntu
SERVER_SSH_KEY=-----BEGIN OPENSSH PRIVATE KEY-----

注意：

SSH_KEY 必须是私钥，不是 .pub 文件。

编写部署脚本 deploy.sh

服务器项目目录：

context-payment.ts

/var/www/personal-website

创建：

context-payment.ts

touch deploy.sh

内容：

context-payment.ts

#!/bin/bash

set -e

cd /var/www/personal-website

echo "Pull latest code"
git pull origin main

echo "Install dependencies"
npm install

echo "Generate Prisma Client"
npx prisma generate

echo "Build Next.js"
npm run build

echo "Restart PM2"
pm2 restart personal-website

 echo "Deploy finished"

增加执行权限：

context-payment.ts

chmod +x deploy.sh

测试：

context-payment.ts

./deploy.sh

创建 GitHub Actions Workflow

项目根目录创建：

context-payment.ts

.github/workflows/deploy.yml

内容：

context-payment.ts

name: Deploy

on:
  push:
    branches:
      - main

  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Deploy Server
        uses: appleboy/ssh-action@v1.2.2
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            cd /var/www/personal-website
            ./deploy.sh

测试自动部署

提交代码：

context-payment.ts

git add .
git commit -m "test deploy"
git push origin main

进入 GitHub：

context-payment.ts

Actions
 ↓
Deploy

可以看到：

context-payment.ts

Queued
 ↓
Running
 ↓
Completed

部署成功后，服务器上的 PM2 会自动重新加载最新代码。

常见问题

SSH Permission denied

错误：

context-payment.ts

Permission denied (publickey)

检查：

GitHub Secret 是否填写私钥
authorized_keys 是否包含公钥
用户名是否正确

deploy.sh 没有权限

错误：

context-payment.ts

Permission denied

解决：

context-payment.ts

chmod +x deploy.sh

PM2 找不到应用

查看：

context-payment.ts

pm2 list

确认名称：

context-payment.ts

pm2 restart personal-website

优化方向

生产环境还可以进一步优化：

使用 npm ci 替代 npm install
build 失败不重启服务
使用 pm2 reload 实现零停机部署
添加部署日志
添加失败通知
使用 Docker 部署

总结

通过 GitHub Actions + SSH + deploy.sh + PM2，我们实现了一套完整的 Next.js 自动部署流程。

以后只需要：

context-payment.ts

git push

服务器即可自动完成代码更新、依赖安装、项目构建以及服务重启。

这就是现代 Web 项目中常见的 CI/CD 工作流。

# Next # Node # Nginx # github-actions # pm2 # ubuntu

GitHub Actions 自动部署 Next.js 项目到 Ubuntu 服务器完整指南

GitHub Actions 自动部署 Next.js 项目到 Ubuntu 服务器完整指南

什么是自动部署

整体架构

配置服务器 SSH 密钥

添加 SSH 公钥

配置 GitHub Secrets

编写部署脚本 deploy.sh

创建 GitHub Actions Workflow

测试自动部署

常见问题

SSH Permission denied

deploy.sh 没有权限

PM2 找不到应用

优化方向

总结

评论 (0)

发表看法

关联知识节点

依赖注入在 React 中的应用

DDD 领域驱动设计概论

微前端架构演变

GitHub Actions 自动部署 Next.js 项目到 Ubuntu 服务器完整指南

GitHub Actions 自动部署 Next.js 项目到 Ubuntu 服务器完整指南

什么是自动部署

整体架构

配置服务器 SSH 密钥

添加 SSH 公钥

配置 GitHub Secrets

编写部署脚本 deploy.sh

创建 GitHub Actions Workflow

测试自动部署

常见问题

SSH Permission denied

deploy.sh 没有权限

PM2 找不到应用

优化方向

总结

评论 (0)

发表看法

关联知识节点

依赖注入在 React 中的应用

DDD 领域驱动设计概论

微前端架构演变