Vue3 SSR HTTP 服务模式使用指南

概述

HTTP 服务模式是 Vue3 SSR 的推荐实现方式，相比进程模式具有更好的性能和可维护性。

快速开始

1. 安装依赖

``bash∫ cd resources/vue3-ssr npm install


<h3 id="2-启动-ssr-服务">2. 启动 SSR 服务</h3>
方式一：使用启动脚本（推荐）

bash
./start.sh

方式二：直接启动
bash
node ssr-server.js

方式三：使用 PM2（生产环境）
bash
pm2 start ssr-server.js --name vue-ssr
pm2 save

<h3 id="3-配置-php">3. 配置 PHP</h3>
在 config/view.php 中配置：

php
'vue3_ssr' => [
    'enabled' => true,
    'mode' => 'http', // 使用 HTTP 模式
    'ssr_server_url' => 'http://127.0.0.1:3000',
    'http_timeout' => 10,
],

<h2 id="配置说明">配置说明</h2>
<h3 id="完整配置选项">完整配置选项</h3>
php
'vue3_ssr' => [
    // 是否启用 SSR
    'enabled' => true,
// 渲染模式：'http'（推荐）或 'process'（已废弃）
    'mode' => 'http',
// HTTP 模式配置
    'ssr_server_url' => 'http://127.0.0.1:3000', // SSR 服务地址
    'http_timeout' => 10, // HTTP 请求超时时间（秒）
// 进程模式配置（仅在 mode='process' 时使用）
    'node_path' => 'node',
    'ssr_script_path' => null,
// 客户端激活配置
    'enable_hydration' => true,
    'vue_cdn' => 'https://unpkg.com/vue@3/dist/vue.esm-browser.js',
],

<h3 id="环境变量">环境变量</h3>
可以通过环境变量配置服务：
bash
PORT=3000 HOST=127.0.0.1 node ssr-server.js

<h2 id="api-端点">API 端点</h2>
<h3 id="post-render">POST /render</h3>
渲染 Vue 组件为 HTML。
请求示例：
bash
curl -X POST http://127.0.0.1:3000/render \
  -H "Content-Type: application/json" \
  -d '{
    "template": "{{ message }}",
    "props": {
      "message": "Hello World"
    }
  }'

响应示例：
json
{
  "html": "Hello World",
  "error": null
}

<h3 id="get-health">GET /health</h3>
健康检查端点。
请求示例：
bash
curl http://127.0.0.1:3000/health

响应示例：
json
{
  "status": "ok",
  "service": "Vue3 SSR Server",
  "version": "1.0.0"
}

<h2 id="使用示例">使用示例</h2>
<h3 id="php-代码示例">PHP 代码示例</h3>
php
use function view;
// 渲染 Vue 模板
$html = view('user/profile', ['user' => $user], 'vue');
// 渲染完整的 HTML 页面
$html = view('user/profile', ['user' => $user], 'vue')->renderFullPage();
// 渲染并启用客户端激活
$html = view('user/profile', ['user' => $user], 'vue')->renderWithHydration();

<h2 id="性能对比">性能对比</h2>
| 模式      | 单次渲染时间 | 吞吐量        | 内存占用 | 推荐场景 |
| --------- | ------------ | ------------- | -------- | -------- |
| HTTP 模式 | 5-20ms       | 100-500 req/s | 中       | 生产环境 |
| 进程模式  | 100-300ms    | 10-30 req/s   | 高       | 不推荐   |
<h2 id="故障排查">故障排查</h2>
<h3 id="问题-1-服务无法启动">问题 1: 服务无法启动</h3>
症状： 运行 node ssr-server.js 时报错
解决方案：
检查 Node.js 是否安装：node --version

检查依赖是否安装：npm install

检查端口是否被占用：lsof -i :3000

<h3 id="问题-2-php-无法连接服务">问题 2: PHP 无法连接服务</h3>
症状： PHP 报错 "Failed to connect to SSR server"
解决方案：
检查服务是否运行：访问 http://127.0.0.1:3000/health

检查防火墙设置
检查 ssr_server_url 配置是否正确

检查服务日志
<h3 id="问题-3-渲染结果为空或错误">问题 3: 渲染结果为空或错误</h3>
症状： 返回的 HTML 为空或格式不正确
解决方案：
查看服务日志
检查组件代码是否正确
检查 Vue 版本兼容性
检查 props 数据格式
<h3 id="问题-4-性能问题">问题 4: 性能问题</h3>
症状： 渲染速度慢
解决方案：
确保使用 HTTP 模式（不是进程模式）
检查网络延迟
考虑使用缓存
优化组件代码
<h2 id="生产环境部署">生产环境部署</h2>
<h3 id="使用-pm2">使用 PM2</h3>
bash
安装 PM2
npm install -g pm2
启动服务
pm2 start resources/vue3-ssr/ssr-server.js --name vue-ssr
设置开机自启
pm2 startup
pm2 save
查看状态
pm2 status
查看日志
pm2 logs vue-ssr
重启服务
pm2 restart vue-ssr
停止服务
pm2 stop vue-ssr

<h3 id="使用-systemdlinux">使用 systemd（Linux）</h3>
创建服务文件 /etc/systemd/system/vue-ssr.service：

ini
[Unit]
Description=Vue3 SSR Server
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/framework/resources/vue3-ssr
ExecStart=/usr/bin/node ssr-server.js
Restart=always
RestartSec=10
Environment=PORT=3000
Environment=HOST=127.0.0.1
[Install]
WantedBy=multi-user.target

启动服务：
bash
sudo systemctl enable vue-ssr
sudo systemctl start vue-ssr
sudo systemctl status vue-ssr

<h2 id="监控和日志">监控和日志</h2>
<h3 id="查看服务日志">查看服务日志</h3>
PM2：
bash
pm2 logs vue-ssr

systemd：
bash
sudo journalctl -u vue-ssr -f

<h3 id="健康检查">健康检查</h3>
可以设置定时任务检查服务健康状态：
bash
添加到 crontab
/5    * curl -f http://127.0.0.1:3000/health || systemctl restart vue-ssr

<h2 id="注意事项">注意事项</h2>
端口配置：确保 SSR 服务端口与 PHP 配置中的 ssr_server_url 一致

防火墙：如果 SSR 服务在远程服务器，需要开放相应端口
资源限制：生产环境建议设置适当的进程数和内存限制
错误处理：建议配置错误监控和告警
版本兼容：确保 Vue 版本与 @vue/server-renderer 版本兼容

<h2 id="迁移指南">迁移指南</h2>
<h3 id="从进程模式迁移到-http-模式">从进程模式迁移到 HTTP 模式</h3>
安装依赖
bash
   cd resources/vue3-ssr
   npm install
   
启动服务
bash
   node ssr-server.js
   
更新配置
php
   'vue3_ssr' => [
       'enabled' => true,
       'mode' => 'http', // 改为 http
       'ssr_server_url' => 'http://127.0.0.1:3000',
   ],


测试验证
   - 访问健康检查端点
   - 测试渲染功能
   - 检查性能提升
常见问题
Q: 可以同时运行多个 SSR 服务实例吗？
A: 可以，但需要配置不同的端口，并使用负载均衡器分发请求。
Q: HTTP 模式支持 HTTPS 吗？

A: 支持，只需将 ssr_server_url 配置为 https:// 开头即可。但需要配置 SSL 证书。


Q: 如何调试渲染问题？

A: 可以查看服务日志，或者在组件代码中添加 console.log` 输出。

Q: 性能优化建议？

使用 HTTP 模式（而不是进程模式）

启用缓存

优化组件代码

使用 CDN 加载 Vue 资源

考虑使用预渲染