前端项目部署到 Hetzner 服务器实践总结
项目背景
- 项目:ShowcaseFrontEnd(React + Vite 个人主页,GitHub: kkju1123/ShowcaseFrontEnd)
- 部署目标:Hetzner 德国服务器(46.225.151.105,cx23 配置,已在跑 WireGuard)
- 域名:keke-labs.com(Namecheap 购买)
一、服务器环境准备
1. SSH 登录服务器
ssh root@46.225.151.105
Hetzner 默认用户是 root(区别于 AWS 的 ubuntu)。如果本地已配置过 SSH Agent 或 ~/.ssh/config,可能会自动完成密钥认证,不需要手动输入密码。
2. 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
验证安装:
node -v
npm -v
二、拉取代码并构建
1. 克隆仓库
git clone https://github.com/kkju1123/ShowcaseFrontEnd.git
cd ShowcaseFrontEnd
2. 安装依赖并构建
npm install
npm run build
构建产物会生成在 dist 目录,确认一下:
ls dist
常见报错:大小写不一致导致找不到文件
报错示例:Could not resolve "./assets/avator2.jpg"。原因是 Mac 本地开发时文件系统不区分大小写(比如仓库里实际文件是 avator2.JPG),但 Linux 服务器严格区分大小写,导致找不到文件。
排查:
ls src/assets/
修复(将服务器上的文件重命名,对齐代码里的引用):
mv src/assets/avator2.JPG src/assets/avator2.jpg
重新构建:
npm run build
三、安装 Nginx 并部署静态文件
1. 安装 Nginx
sudo apt update
sudo apt install nginx -y
2. 拷贝构建产物到网站目录
sudo cp -r dist/* /var/www/html/
3. 检查 Nginx 状态
sudo systemctl status nginx
如果没有自动启动:
sudo systemctl start nginx
sudo systemctl enable nginx
4. 服务器本地测试(排除防火墙干扰)
curl localhost
能看到 HTML 内容返回,说明 Nginx 本身工作正常。
四、防火墙放行端口(关键踩坑点)
浏览器访问一直转圈,通常是 Hetzner 云防火墙没放行 80/443 端口,不是网站本身的问题。
去 Hetzner 控制台防火墙页面,添加入站规则:
- 协议 TCP,端口 80,来源 Any(0.0.0.0/0)
- 协议 TCP,端口 443,来源 Any(0.0.0.0/0,为后续 HTTPS 准备)
五、域名解析配置(Namecheap)
1. 域名 Suspend 问题
如果域名状态显示 "Domain suspended. Contacts verification needed.",这是 ICANN 强制要求的联系人信息验证流程(注册或变更联系信息后 15 天内需邮件验证),不是违规。去邮箱找验证邮件点击确认即可解除。
2. 添加 A 记录
Namecheap 后台 → Domain List → 选中域名 → Advanced DNS → Host Records → Add New Record:
- Type: A Record
- Host: @
- Value: 46.225.151.105
- TTL: Automatic
如果发现已有旧的 A 记录指向别的 IP,直接编辑修改成新 IP,不要新建重复记录,避免解析冲突。
3. 验证解析是否生效
不要用 ping 判断(很多服务器防火墙默认屏蔽 ICMP,ping 不通不代表没生效),用 dig 命令更准确:
dig keke-labs.com +short
dig keke-labs.com @8.8.8.8 +short
如果本地终端 ping/浏览器还显示旧内容,是本地 DNS 缓存问题,清一下缓存(Mac):
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
六、配置 HTTPS(Certbot)
DNS 解析确认生效后:
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d keke-labs.com -d www.keke-labs.com
跟随提示完成即可自动配置好 HTTPS 证书和续期。
七、后续更新流程
每次本地改完代码,更新到服务器上线的完整流程:
本地(Mac)提交推送:
git add .
git commit -m "更新内容"
git push
服务器拉取并重新部署:
cd ~/ShowcaseFrontEnd && git pull && npm install && npm run build && sudo cp -r dist/* /var/www/html/
一键部署脚本(推荐)
创建脚本:
nano ~/deploy.sh
脚本内容(粘贴进编辑器):
#!/bin/bash
cd ~/ShowcaseFrontEnd
git pull
npm install
npm run build
sudo cp -r dist/* /var/www/html/
echo "部署完成!"
赋予执行权限:
chmod +x ~/deploy.sh
以后每次更新,只需要执行:
~/deploy.sh
八、后续可优化方向
- 配置 GitHub Actions,实现本地 push 后服务器自动拉取部署,无需手动 SSH 操作
- 定期检查 Certbot 证书自动续期是否正常:
sudo certbot renew --dry-run - 考虑给这台服务器加上 fail2ban 等基础防护,毕竟现在同时跑着 WireGuard 和对外网站两类服务
