利用 PHPStudy（Mac 版）部署 Nuxt3 node-server 模式项目完整教程

最新推荐文章于 2026-03-28 03:31:33 发布

原创最新推荐文章于 2026-03-28 03:31:33 发布 · 1.2k 阅读

11 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#macos #vim #编辑器

利用 PHPStudy（Mac 版）部署 Nuxt3 node-server 模式项目完整教程

一、教程概述

本文针对 Mac 系统下的 PHPStudy（含小皮面板 XP.CN），详细讲解如何部署 Nuxt3 node-server 模式产物。node-server 模式是 Nuxt3 默认的服务端部署方式，依赖 Node.js 环境运行，支持 SSR 服务端渲染、服务端接口代理、动态路由等核心能力，PHPStudy 在此过程中主要承担「反向代理」角色，实现自定义域名/端口访问 Nuxt 服务。

二、前置环境准备

1. 基础环境校验

Node.js：Mac 需安装 Node.js 16+ 版本，终端执行 node -v 验证（如输出 v18.18.0 则符合要求）；
PHPStudy：确保 Mac 版 PHPStudy（或小皮面板 XP.CN）已安装并正常启动，能打开「站点/网站」管理界面；
Nuxt 产物：已通过 pnpm run build 生成 Nuxt node-server 模式产物（默认输出到项目根目录 .output 文件夹）。

2. 产物存放

将 Nuxt 项目的 .output 目录复制到 PHPStudy 网站根目录（不同版本路径略有差异）：

传统 PHPStudy for Mac：/Applications/PHPStudy/WWW/nuxt-pc/.output；
小皮面板 XP.CN：/Applications/XP/WWW/nuxt-pc/.output；
（nuxt-pc 为自定义项目文件夹，可自行命名）

三、步骤 1：启动 Nuxt Node 服务

node-server 模式的核心是先启动独立的 Node 服务，PHPStudy 仅做反向代理转发请求，无需直接解析产物。

打开 Mac 终端，进入 Nuxt 项目目录：

# 传统 PHPStudy 路径
cd /Applications/PHPStudy/WWW/nuxt-pc
# 小皮面板 XP.CN 路径
# cd /Applications/XP/WWW/nuxt-pc

启动 Node 服务（指定端口避免冲突，示例用 3001）：
```
PORT=3001 node .output/server/index.mjs
```
验证服务：终端显示 Nitro server running on http://0.0.0.0:3001，浏览器访问 http://127.0.0.1:3001 能显示 Nuxt 页面，说明服务启动成功。

四、步骤 2：PHPStudy 配置反向代理站点

1. 新建站点

打开 PHPStudy（或小皮面板），点击左侧「站点/网站」→「新增/创建网站」；
填写站点核心配置：

配置项	填写内容
站点名称	自定义（如：nuxt-node-pc）
域名	自定义（如：nuxt.pc.com，后续需配置本地 hosts）
端口	自定义（如：8080，避免与 Node 服务端口 3001、PHPStudy 默认 80 端口冲突）
网站根目录	选择项目文件夹（如 `/Applications/PHPStudy/WWW/nuxt-pc`，仅占位无需指向 `.output`）
PHP 版本	选择「纯静态」（无需 PHP 解析）
服务器	选择「Nginx」（反向代理仅 Nginx 支持）

点击「保存/创建」，暂不启动站点。

2. 配置 Nginx 反向代理（核心）

在站点列表中找到新建的「nuxt-node-pc」，点击「配置/Nginx 配置」；

替换 location / 段为以下反向代理规则：

server {
    listen 8080; # 对应站点配置的端口
    server_name nuxt.pc.com; # 对应站点配置的域名

    # 反向代理核心规则
    location / {
        proxy_pass http://127.0.0.1:3001; # 指向启动的 Node 服务地址
        
        # 必加：传递请求头，解决后端鉴权/跨域问题
        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_connect_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 可选：补充接口代理规则（若 Nuxt 内置 proxy 失效时使用）
    # location /proxy/ {
    #     proxy_pass http://你的后端接口地址/;
    #     proxy_set_header Host 你的后端域名;
    # }
}

保存配置，回到 PHPStudy 启动该站点。

五、步骤 3：配置 Mac 本地 Hosts

让 Mac 识别自定义域名（如 nuxt.pc.com），需修改 hosts 文件：

终端执行命令编辑 hosts：
```
sudo vi /etc/hosts
```
按 i 进入编辑模式，添加一行：
```
127.0.0.1 nuxt.pc.com
```
按 esc 退出编辑，输入 :wq 保存并退出；
刷新 DNS 缓存：
```
dscacheutil -flushcache
```

六、步骤 4：访问验证与后台运行

1. 访问验证

浏览器输入 http://nuxt.pc.com:8080（自定义域名+端口），能正常显示 Nuxt 页面，且动态路由、接口代理均生效，说明部署成功。

2. Node 服务后台运行（可选）

默认终端关闭后 Node 服务会停止，可通过 pm2 实现后台运行：

安装 pm2（全局）：
```
npm i -g pm2
```

后台启动 Nuxt 服务：

cd /Applications/PHPStudy/WWW/nuxt-pc
pm2 start .output/server/index.mjs --name "nuxt-pc" --env PORT=3001

常用 pm2 命令：

pm2 list # 查看服务状态
pm2 restart nuxt-pc # 重启服务
pm2 stop nuxt-pc # 停止服务

七、常见问题排查

1. 访问域名 404/无法打开

检查 Node 服务是否正常运行（终端是否有 Nitro server 提示）；
核对 Nginx 配置中 proxy_pass 地址是否为 http://127.0.0.1:3001（端口与启动时一致）；
确认 hosts 文件配置正确，执行 ping nuxt.pc.com 能返回 127.0.0.1。

2. 端口被占用

终端执行 lsof -i :3001（替换为占用端口）查看进程；
执行 kill -9 进程ID 关闭占用程序，重新启动 Node 服务。

3. 接口代理 502 错误

检查 Nuxt nuxt.config.ts 中 routeRules.proxy 是否配置 changeOrigin: true；
验证后端接口地址是否可访问（终端执行 curl 后端接口地址）；
可改用 Nginx 配置中的 location /proxy/ 直接代理接口（更稳定）。

4. 站点启动失败

检查 Nginx 配置是否有语法错误（PHPStudy 配置界面会提示）；
确保站点端口（8080）未被其他程序占用。

八、总结

利用 PHPStudy（Mac 版）部署 Nuxt3 node-server 模式的核心逻辑是「Node 服务独立运行 + PHPStudy Nginx 反向代理」：

Node 服务负责处理 Nuxt SSR 渲染、动态路由、接口代理等核心逻辑；
PHPStudy 仅承担「域名/端口转发」角色，让用户通过自定义域名便捷访问；
该方案兼顾了 Nuxt node-server 模式的动态能力，又利用 PHPStudy 简化了域名/端口管理，适合本地开发、测试环境快速部署。