如何在PHP服务器端渲染React组件？无需NextJS/Remix

核心思路 #

利用PHP的V8扩展执行Vite构建后的React SSR脚本，在WordPress短代码处理流程中完成服务器端渲染，输出可被搜索引擎抓取的静态HTML，同时保留客户端交互能力。

步骤1：环境与项目准备 #

• 确保PHP环境安装并启用V8JS扩展（可通过php -m | grep v8js验证）
• 用Vite初始化React项目，确保已安装react、react-dom、@vitejs/plugin-react依赖

步骤2：配置Vite SSR构建 #

修改项目根目录的vite.config.js，添加SSR相关配置：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    ssr: true,
    rollupOptions: {
      input: {
        // 定义SSR入口文件
        ssr: './src/ssr.jsx',
        // 客户端hydrate入口
        client: './src/client.jsx'
      }
    }
  }
});

编写SSR渲染逻辑 #

创建src/ssr.jsx，导出接收props并返回渲染HTML的函数：

import React from 'react';
import { renderToString } from 'react-dom/server';
import YourComponent from './YourComponent';

// 暴露给PHP调用的全局函数
global.renderReactComponent = (props) => {
  const html = renderToString(<YourComponent {...props} />);
  // 返回HTML和客户端hydrate所需的props（序列化后）
  return {
    html,
    props: JSON.stringify(props)
  };
};

编写客户端hydrate逻辑 #

创建src/client.jsx，负责接管服务器渲染的HTML，恢复交互：

import React from 'react';
import { hydrateRoot } from 'react-dom/client';
import YourComponent from './YourComponent';

// 从页面中获取服务器传递的props
const propsElement = document.getElementById('react-component-props');
if (propsElement) {
  const props = JSON.parse(propsElement.textContent);
  hydrateRoot(
    document.getElementById('react-component-root'),
    <YourComponent {...props} />
  );
}

执行npm run build，生成SSR脚本（dist/ssr.js）和客户端脚本（dist/client.js），将这两个文件复制到WordPress插件目录中。

步骤3：WordPress插件集成PHP与SSR #

在插件主文件中编写短代码处理函数：

function react_component_shortcode($atts) {
  // 处理短代码参数，作为React组件的props
  $props = shortcode_atts([
    'title' => '默认标题',
    'content' => '默认内容'
  ], $atts);

  // 初始化V8引擎
  $v8 = new V8Js();

  // 加载Vite构建后的SSR脚本
  $ssrScript = file_get_contents(plugin_dir_path(__FILE__) . 'dist/ssr.js');
  $v8->executeString($ssrScript);

  // 调用全局的renderReactComponent函数，传递props
  $result = $v8->executeString(sprintf(
    'renderReactComponent(%s)',
    json_encode($props)
  ));

  // 组装最终输出：渲染后的HTML + 隐藏的props + 客户端hydrate脚本
  $output = sprintf(
    '<div id="react-component-root">%s</div>
    <script type="application/json" id="react-component-props">%s</script>
    <script src="%s"></script>',
    $result['html'],
    $result['props'],
    plugin_dir_url(__FILE__) . 'dist/client.js'
  );

  return $output;
}
add_shortcode('react_component', 'react_component_shortcode');

关键优化点 #

• 缓存渲染结果：使用WordPress的wp_cache_set和wp_cache_get，根据props哈希值缓存SSR输出，减少V8执行次数
• 错误处理：给V8执行逻辑添加try-catch，避免组件渲染失败导致页面崩溃
• 资源加载优化：将客户端脚本注册为WordPress脚本（用wp_enqueue_script），而非直接输出，便于依赖管理和版本控制

内容的提问来源于stack exchange，提问作者Byeongin Yoon