在现代Web开发中，引入React构建复杂的用户界面已经成为提升WordPress交互体验的常见手段。然而，许多开发者在初期往往选择Roots Sage作为基础框架，因为Sage提供了一套相对现代化的前端构建工具链。但随着项目规模的扩大和React组件数量的激增，Sage基于传统WordPress主题目录的架构开始暴露出耦合度过高的问题。此时，将项目底层迁移至Bedrock框架，不仅能彻底解耦WordPress核心与应用代码，还能为React提供更纯粹的运行环境。
为什么从Sage迁移到Bedrock是React开发的必然选择
Roots Sage本质上依然是一个WordPress主题。它的核心职责是控制网站的视觉呈现和模板渲染。当我们在Sage中引入React时，通常是将React组件打包后注入到Sage的Blade模板中。这种模式下，React应用的生命周期与WordPress主题深度绑定。一旦我们需要对React应用进行独立部署、服务端渲染（SSR）或者与外部API进行高频交互时，主题目录的边界就会成为阻碍。所有的前端依赖、路由配置和状态管理都被困在主题文件夹内，难以实现真正的工程化拆分。
相比之下，Bedrock采取了一种完全不同的系统设计思路。它并非一个主题，而是一个现代化的WordPress应用程序引导程序。Bedrock将WordPress核心文件隔离在web/wp目录下，而所有的自定义主题、插件和前端应用代码则放置在web/app目录中。这种物理层面的隔离意味着，我们可以将React应用视为一个独立的微前端或者大型插件来管理。在Bedrock架构下，React项目可以拥有自己独立的依赖锁定文件、独立的构建流程，甚至可以脱离WordPress主题的约束，通过自定义REST API或GraphQL与后端通信。
从系统设计的角度来看，这种迁移是从页面驱动向应用驱动的转变。Sage关注的是如何更好地渲染页面，而Bedrock关注的是如何更好地组织整个应用程序。对于React开发者而言，Bedrock提供的标准化目录结构和环境变量管理机制，使得前端工程化中常见的持续集成和持续部署变得异常清晰。开发者不再需要将前端代码硬塞进主题的functions文件中，而是可以在应用层级统筹所有的前端资源。
迁移过程中的核心目录结构与依赖管理调整
从Sage迁移到Bedrock，最直观的改变是目录结构的重组。在Sage中，你的package.json、webpack配置文件以及React源代码通常都位于wp-content/themes/your-theme目录下。而在Bedrock中，整个项目结构被重新定义。Bedrock根目录下包含了composer.json用于管理PHP依赖，而前端资源的管理则可以根据需要灵活放置。一种推荐的做法是，在Bedrock的web/app/themes/your-theme目录下仅保留极简的PHP模板文件，而将React应用的核心代码提升到项目根目录下的frontend或client目录中，或者将其封装为一个独立的Must Use Plugin（位于web/app/mu-plugins目录）。
依赖管理的调整是迁移的关键环节。在Sage模式下，前端依赖和主题PHP逻辑混杂在一起。迁移到Bedrock后，我们应当明确区分PHP依赖与JavaScript依赖。PHP层面的依赖（如高级自定义字段等）通过Bedrock根目录的Composer进行管理，而React相关的依赖（如React、ReactDOM、Redux等）则通过前端目录下的package.json进行管理。这种分离不仅减少了主题包的体积，还避免了在部署环境中安装不必要的Node.js模块。
下面是一个典型的Bedrock项目结构下，React应用独立目录的package.json配置示例。通过定义脚本命令，我们可以将React构建产物直接输出到WordPress主题或插件的资源目录中。
{
"name": "wp-react-app",
"version": "1.0.0",
"scripts": {
"dev": "vite",
"build": "vite build",
"watch": "vite build --watch"
},
"dependencies": {
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-router-dom": "^6.20.0"
},
"devDependencies": {
"@vitejs/plugin-react": "^4.2.0",
"vite": "^5.0.0"
}
}在Bedrock架构下配置React构建流程与资源加载
构建流程的解耦是迁移的核心。在Sage中，我们通常使用其内置的Bud构建工具，它与Sage的模板渲染深度集成。迁移到Bedrock后，为了最大化React的灵活性，建议使用Vite或标准的Webpack进行独立配置。我们需要配置Vite，将React应用的入口文件编译打包，并指定输出目录为Bedrock结构下的主题或插件资源文件夹。这样，React应用就不再依赖于WordPress的PHP模板引擎进行渲染，而是作为一个独立的单页应用或局部岛屿组件注入到页面中。
资源加载机制也需要相应调整。在传统的Sage主题中，我们通过PHP的wp_enqueue_script函数加载资源。在Bedrock架构下，如果我们将React应用封装为独立的插件，可以在插件的主文件中注册钩子。我们需要在WordPress初始化阶段，将Vite打包生成的带有哈希值的JavaScript和CSS文件注入到页面头部。同时，为了处理React Router等前端路由，我们还需要配置WordPress的重写规则，确保所有的前端路由都能被正确映射到React应用的入口文件。
以下是在Bedrock自定义插件中加载React构建资源的PHP代码示例。该代码会读取Vite生成的manifest.json文件，确保每次加载的都是最新的带有哈希值的资源文件，从而避免浏览器缓存问题。
<?php
/**
* Plugin Name: React App Integration
* Description: 在Bedrock架构下加载React应用
*/
function enqueue_react_app_assets() {
// 获取Vite构建后的manifest文件
$manifest_path = WP_CONTENT_DIR . '/plugins/react-app/dist/manifest.json';
if (file_exists($manifest_path)) {
$manifest = json_decode(file_get_contents($manifest_path), true);
// 加载主入口JS文件
if (isset($manifest['main.js'])) {
wp_enqueue_script(
'react-app-main',
plugins_url('dist/' . $manifest['main.js']['file'], __FILE__),
[],
null,
true
);
}
// 加载主入口CSS文件
if (isset($manifest['main.css'])) {
wp_enqueue_style(
'react-app-style',
plugins_url('dist/' . $manifest['main.css']['file'], __FILE__),
[],
null
);
}
}
}
add_action('wp_enqueue_scripts', 'enqueue_react_app_assets');通过上述配置，React应用在Bedrock架构下实现了完全的解耦运行。前端开发者可以专注于Vite配置和React组件的开发，而无需关心WordPress核心的更新或主题模板的变动。这种架构不仅提升了开发效率，也为后续引入服务端渲染或同构渲染打下了坚实的基础。当系统需要扩展时，Bedrock清晰的目录结构和环境隔离机制将确保整个应用具备极高的可维护性。
Roots SageBedrockWordPress开发框架修改时间：2026-08-21 02:09:14