首页/资讯中心/详情

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

利用 PHPStudy（Mac 版）部署 Nuxt3 node-server 模式项目完整教程
📅 发布时间：2026/6/21 14:28:19

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

一、教程概述

本文针对 Mac 系统下的 PHPStudy（含小皮面板 XP.CN），详细讲解如何部署 Nuxt3node-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生成 Nuxtnode-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 仅做反向代理转发请求，无需直接解析产物。

  1. 打开 Mac 终端，进入 Nuxt 项目目录：
    # 传统 PHPStudy 路径cd/Applications/PHPStudy/WWW/nuxt-pc# 小皮面板 XP.CN 路径# cd /Applications/XP/WWW/nuxt-pc
  2. 启动 Node 服务（指定端口避免冲突，示例用 3001）：
    PORT=3001node .output/server/index.mjs
  3. 验证服务：终端显示Nitro server running on http://0.0.0.0:3001，浏览器访问http://127.0.0.1:3001能显示 Nuxt 页面，说明服务启动成功。

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

1. 新建站点

  1. 打开 PHPStudy（或小皮面板），点击左侧「站点/网站」→「新增/创建网站」；
  2. 填写站点核心配置：
配置项填写内容
站点名称自定义（如：nuxt-node-pc）
域名自定义（如：nuxt.pc.com，后续需配置本地 hosts）
端口自定义（如：8080，避免与 Node 服务端口 3001、PHPStudy 默认 80 端口冲突）
网站根目录选择项目文件夹（如/Applications/PHPStudy/WWW/nuxt-pc，仅占位无需指向.output）
PHP 版本选择「纯静态」（无需 PHP 解析）
服务器选择「Nginx」（反向代理仅 Nginx 支持）
  1. 点击「保存/创建」，暂不启动站点。

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

  1. 在站点列表中找到新建的「nuxt-node-pc」，点击「配置/Nginx 配置」；
  2. 替换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 你的后端域名; # } }
  3. 保存配置，回到 PHPStudy 启动该站点。

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

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

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

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

1. 访问验证

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

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

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

  1. 安装 pm2（全局）：
    npmi -g pm2
  2. 后台启动 Nuxt 服务：
    cd/Applications/PHPStudy/WWW/nuxt-pc pm2 start .output/server/index.mjs --name"nuxt-pc"--envPORT=3001
  3. 常用 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 错误

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

4. 站点启动失败

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

八、总结

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

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