GitHub Actions自动化部署Vue项目到宝塔服务器

type

status

date

slug

summary

GitHub Actions自动化部署Vue项目到宝塔服务器

通过GitHub Actions自动化部署Vue项目到宝塔服务器，可实现代码推送后自动构建和部署，极大提升开发效率，减少人工操作错误。整个流程包括服务器环境准备、SSH密钥对生成与配置、GitHub仓库配置以及GitHub Actions工作流配置四个关键步骤。这套方案特别适合个人开发者和小型团队，无需依赖复杂的云服务或付费部署工具，即可实现高效、安全的持续集成/持续部署(CI/CD)。

一、服务器环境准备

1.1 宝塔面板安装与基础配置

宝塔面板是一个功能强大的Linux服务器管理面板，提供可视化的Web界面来管理服务器。你可以从宝塔官网获取最新的安装脚本和详细文档。

对于Ubuntu/Debian系统，使用以下命令安装：

对于CentOS系统：

安装完成后，在面板中安装必要的服务：

Node.js：用于本地构建测试（可选）

Nginx：用于Web服务器

提示：宝塔官网（https://www.bt.cn/）提供了详细的安装文档和视频教程，建议首次使用的用户参考官方指南进行安装。

1.2 创建网站并配置Nginx

在宝塔面板中创建网站：

进入"网站"模块，点击"添加站点"

设置域名或IP地址

设置网站根目录（如：/www/wwwroot/yourdomain.com）

不选择PHP版本（前端项目无需PHP）

创建完成后，配置Nginx以支持Vue路由：

关键配置说明：

root：指向Vue项目构建后的部署目录

try_files：确保Vue Router的History模式正常工作

静态资源缓存配置：提升页面加载性能

1.3 安装必要工具

确保服务器已安装unzip工具（用于解压构建产物）：

二、SSH密钥对生成与配置

2.1 生成SSH密钥对

在本地机器生成SSH密钥对：

建议：

密钥文件名可指定为github_actions_rsa以便区分

密码留空，支持自动化部署

妥善保管私钥文件

2.2 配置服务器公钥

将公钥添加到服务器的授权列表：

权限设置注意事项：

如使用宝塔面板默认用户，可能需要调整目录所有者

建议创建专用部署用户，避免使用root账户

2.3 测试SSH连接

验证SSH免密登录是否配置成功：

三、GitHub仓库配置

3.1 设置Repository Secrets

在GitHub仓库中配置以下机密变量：

进入仓库 → Settings → Secrets and variables → Actions

添加以下secrets：

名称	值	说明
`SSH_HOST`	服务器IP地址	如：`123.456.789.0`
`SSH_USERNAME`	SSH用户名	如：`root`或`btuser`
`SSH_PRIVATE_KEY`	SSH私钥内容	完整的私钥文件内容
`DEPLOY_DIR`	部署目录路径	如：`/www/wwwroot/yourdomain.com`

3.2 验证配置

确保所有secrets配置正确，特别注意：

SSH_PRIVATE_KEY包含完整的私钥内容（包括头尾标识）

DEPLOY_DIR路径与宝塔面板中设置的网站根目录一致

SSH_HOST为服务器的公网IP地址

四、GitHub Actions工作流配置

在项目根目录创建.github/workflows/deploy.yml文件：

五、部署流程说明

5.1 触发条件

推送代码到master分支时自动触发

可根据需要修改为其他分支或添加tag触发条件

5.2 构建过程

代码检出：获取最新代码

环境准备：安装Node.js和项目依赖

项目构建：执行npm run build生成dist目录

文件压缩：将 dist 内容打包为zip文件

5.3 部署过程

文件传输：通过SCP将构建产物传输到服务器

清理旧文件：删除部署目录中的旧文件

解压部署：解压新的构建产物

服务重载：重新加载Nginx配置

六、常见问题与解决方案

6.1 权限问题

问题：部署时提示权限不足解决：

6.2 Nginx重载失败

问题：nginx -s reload执行失败解决：

检查Nginx配置文件语法：nginx -t

确保SSH用户有执行nginx命令的权限

可使用sudo nginx -s reload或配置sudoers

6.3 构建失败

问题：npm install或npm run build失败解决：

检查package.json中的scripts配置

确保Node.js版本与项目要求匹配

检查是否有私有依赖需要配置访问权限

6.4 路由404问题

问题：Vue Router的History模式路由无法访问解决：确保Nginx配置中包含try_files $uri $uri/ /index.html;