使用宝塔面板部署这个 Nuxt 4 SSR 项目的完整操作指南

宝塔面板部署 Nuxt 4 SSR 项目

第一步：服务器环境准备

1. 安装宝塔面板（如已安装跳过）

# CentOS
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh ed8484bec

# Ubuntu/Debian
wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh ed8484bec

2. 在宝塔「软件商店」中安装以下软件

软件	版本建议	用途
Nginx	1.24+	反向代理
PM2管理器	最新	Node.js 进程守护
Node.js版本管理器	安装 Node 18+	运行 Nuxt 服务

⚠️ 安装 PM2管理器会自动附带 Node.js，也可以单独通过 Node.js版本管理器切换版本。确保 Node.js ≥ 18。

第二步：上传项目代码

方式 A：Git 拉取（推荐）

在宝塔「终端」中执行：

# 进入网站根目录
cd /www/wwwroot

# 克隆项目
git clone https://github.com/你的用户名/qdgithub-nuxt4.git

# 进入项目目录
cd qdgithub-nuxt4

方式 B：宝塔文件管理器上传

宝塔面板 → 「文件」→ 进入 /www/wwwroot/
上传项目压缩包并解压

第三步：安装依赖 & 构建

在宝塔「终端」中执行：

cd /www/wwwroot/qdgithub-nuxt4

# 安装依赖
npm install

# 构建生产版本
npm run build

构建完成后，产物在 .output/ 目录下：

.output/
├── server/       # Node.js 服务端代码
│   └── index.mjs # 入口文件
└── public/       # 静态资源（CSS/JS/图片）

第四步：配置环境变量

在项目根目录创建 .env 文件：

cd /www/wwwroot/qdgithub-nuxt4
cat > .env << 'EOF'
NUXT_PUBLIC_API_BASE=/api
NUXT_PUBLIC_SITE_URL=https://blog.qdgithub.com
EOF

如果你的 API 后端也在同一台服务器，NUXT_PUBLIC_API_BASE 保持 /api，后面通过 Nginx 代理。

第五步：使用 PM2 启动服务

方式 A：通过宝塔 PM2 管理器（图形化）

宝塔面板 → 「软件商店」→ 「PM2管理器」→ 「设置」
点击「添加项目」
填写：

字段	值
项目名称	`home-nuxt4`
启动文件	`/www/wwwroot/qdgithub-nuxt4/.output/server/index.mjs`
运行目录	`/www/wwwroot/qdgithub-nuxt4`
端口	`3000`

点击「提交」

方式 B：通过终端命令

cd /www/wwwroot/qdgithub-nuxt4

# 启动 PM2
pm2 start .output/server/index.mjs --name home-nuxt4

# 设置开机自启
pm2 save
pm2 startup

启动后验证服务是否正常：

curl http://localhost:3000

如果返回 HTML 内容，说明服务启动成功。

第六步：宝塔添加网站 & 配置 Nginx 反向代理

1. 添加网站

宝塔面板 → 「网站」→ 「添加站点」
填写：

字段	值
域名	`blog.qdgithub.com`
根目录	`/www/wwwroot/qdgithub-nuxt4/.output/public`
PHP版本	纯静态
数据库	不创建

2. 配置 Nginx 反向代理

点击网站名 → 「设置」→ 「配置文件」，替换为以下内容：

server {
    listen 80;
    server_name blog.qdgithub.com;

    # 网站根目录指向 Nuxt 构建的静态资源
    root /www/wwwroot/qdgithub-nuxt4/.output/public;

    # Nuxt 静态资源由 Nginx 直接服务（性能更优）
    location /_nuxt/ {
        expires 365d;
        add_header Cache-Control "public, immutable";
        try_files $uri $uri/ =404;
    }

    # 图片等上传资源长期缓存
    location /images/ {
        expires 365d;
        add_header Cache-Control "public, max-age=31536000, immutable";
        try_files $uri $uri/ =404;
    }

    # API 请求代理到后端服务器
    location /api/ {
        proxy_pass https://blog.qdgithub.com/api/;
        proxy_set_header Host blog.qdgithub.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_ssl_server_name on;
    }

    # Uploads 代理到后端服务器
    location /Uploads/ {
        proxy_pass https://blog.qdgithub.com/Uploads/;
        proxy_set_header Host blog.qdgithub.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_ssl_server_name on;
    }

    # 其他所有请求代理到 Nuxt SSR 服务
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    access_log /www/wwwlogs/blog.qdgithub.com.log;
    error_log /www/wwwlogs/blog.qdgithub.com.error.log;
}

关键说明：

/_nuxt/ 静态资源由 Nginx 直接返回，不走 Node.js，性能更好

/api/ 和 /Uploads/ 代理到你的后端服务器（替代开发环境的 devProxy）

其他所有请求转发到 Nuxt SSR 服务（端口 3000）

保存后，Nginx 会自动重载配置。

第七步：配置 SSL 证书（HTTPS）

宝塔面板 → 「网站」→ 点击网站名 → 「设置」→ 「SSL」
选择「Let's Encrypt」→ 勾选域名 → 点击「申请」
申请成功后，开启「强制HTTPS」

第八步：验证部署

浏览器访问 https://blog.qdgithub.com
检查页面是否正常渲染（SSR 生效）
查看页面源代码（Ctrl+U），确认 HTML 中包含文章内容（而非空壳）

日常维护操作

更新部署

cd /www/wwwroot/qdgithub-nuxt4

# 拉取最新代码
git pull

# 重新安装依赖（如有变更）
npm install

# 重新构建
npm run build

# 重启 PM2 服务
pm2 restart home-nuxt4

查看日志

# PM2 日志
pm2 logs home-nuxt4

# Nginx 日志
tail -f /www/wwwlogs/blog.qdgithub.com.log
tail -f /www/wwwlogs/blog.qdgithub.com.error.log

PM2 常用命令

pm2 status              # 查看所有进程状态
pm2 restart home-nuxt4  # 重启
pm2 stop home-nuxt4     # 停止
pm2 delete home-nuxt4   # 删除
pm2 monit               # 实时监控面板

常见问题排查

问题	原因	解决
页面空白，源码无内容	Node.js 服务未启动	`pm2 restart home-nuxt4`，检查 3000 端口
API 请求 502	Nginx 代理配置错误	检查 `/api/` 代理目标是否可达
静态资源 404	Nginx root 路径不对	确认 root 指向 `.output/public`
样式丢失	`/_nuxt/` 未被 Nginx 正确处理	检查 `/_nuxt/` location 块
Hydration mismatch	SSR/CSR 环境变量不一致	确保 `.env` 和 Nginx 代理配置匹配

整体流程总结：安装环境 → 上传代码 → npm install & build → PM2 启动 → Nginx 反向代理 → SSL 证书，核心就是让 Nginx 把动态请求转发给 Node.js 服务，静态资源直接由 Nginx 处理。