在 WordPress 插件中使用 Vite 构建指南

在 WordPress 插件中使用 Vite 构建指南

基础配置

1. 项目初始化

首先创建基本的项目结构：

mkdir wp-content/plugins/vite-demo
cd wp-content/plugins/vite-demo
pnpm init
pnpm add -D vite @vitejs/plugin-react typescript @types/react @types/react-dom
pnpm add react react-dom

2. Vite 配置

创建 vite.config.ts，关键配置是 base 路径和 manifest：

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

export default defineConfig({
  plugins: [react()],
  // 关键：确保静态资源路径正确
  base: "/wp-content/plugins/vite-demo/dist/",
  build: {
    // 在 outDir 中生成 .vite/manifest.json
    manifest: true,
    rollupOptions: {
      // 覆盖默认的 .html 入口
      input: "/src/main.tsx",
    },
  },
  server: {
    cors: {
      // 通过浏览器访问的源
      origin: "http://localhost:8889",
    },
    host: "0.0.0.0",
    port: 4200,
  },
});

WordPress 集成详解

1. PHP 插件核心文件解析

1.1 插件声明和安全检查

<?php
/**
 * Plugin Name: Vite Demo
 * Description: A WordPress plugin using Vite and React
 * Version: 1.0.0
 * Author: Your Name
 */

// 防止直接访问PHP文件的安全检查
if (!defined('ABSPATH')) {
    exit;
}

// 定义插件常量
define('VITE_DEV_SERVER', 'http://localhost:4200');
define('VITE_DEMO_PATH', plugin_dir_path(__FILE__));  // 获取插件目录的完整服务器路径
define('VITE_DEMO_URL', plugin_dir_url(__FILE__));    // 获取插件目录的完整URL

这段代码的关键点：

• defined('ABSPATH') 检查是 WordPress 插件的标准安全实践，防止用户直接访问 PHP 文件
• plugin_dir_path() 和 plugin_dir_url() 是 WordPress 提供的辅助函数，用于获取插件目录的绝对路径和 URL
• __FILE__ 是 PHP 魔术常量，表示当前文件的完整路径

1.2 管理菜单注册详解

function vite_demo_admin_menu(): void {
    add_menu_page(
        'Vite Demo',         // page_title: 浏览器标题栏显示的文本
        'Vite Demo',         // menu_title: 后台菜单显示的文本
        'manage_options',    // capability: 需要的用户权限，manage_options 通常表示管理员
        'vite-demo',         // menu_slug: 页面的唯一标识符
        'vite_demo_admin_page', // callback: 渲染页面内容的函数
        'dashicons-admin-generic', // icon: WordPress Dashicons 图标
        30                   // position: 菜单显示位置，数字越小越靠上
    );
}
add_action('admin_menu', 'vite_demo_admin_menu');

1.3 资源加载控制器

function vite_demo_enqueue_assets(): void {
    // get_current_screen() 获取当前页面信息
    $screen = get_current_screen();

    // 确保只在插件页面加载资源
    if (!$screen || $screen->base !== 'toplevel_page_vite-demo') {
        return;
    }

    // 注入 WordPress REST API 相关设置到前端
    wp_localize_script('vite-demo-js', 'wpApiSettings', [
        'nonce' => wp_create_nonce('wp_rest'),  // 生成安全令牌
        'root'  => esc_url_raw(rest_url())      // REST API 根路径
    ]);
}
add_action('admin_enqueue_scripts', 'vite_demo_enqueue_assets');

1.4 WordPress 样式冲突处理

function vite_demo_block_wp_admin_css($tag, $handle): string {
    $screen = get_current_screen();
    if (!$screen || $screen->base !== 'toplevel_page_vite-demo') {
        return $tag;
    }

    // 需要阻止加载的 WordPress 默认样式
    $blocked_handles = [
        'forms',
        // 'common',  // 可以根据需要添加其他样式
    ];

    // 阻止加载指定的样式和所有 wp-admin 相关样式
    if (in_array($handle, $blocked_handles) || strpos($handle, 'wp-admin') !== false) {
        return '';
    }
    return $tag;
}
add_filter('style_loader_tag', 'vite_demo_block_wp_admin_css', 10, 2);

1.5 REST API 实现

// 注册 API 路由
function vite_demo_register_rest_routes(): void {
    register_rest_route('vite-demo/v1', '/settings', [
        [
            'methods' => WP_REST_Server::READABLE,  // GET 请求
            'callback' => 'vite_demo_get_settings', // 处理函数
            'permission_callback' => function () {   // 权限检查
                return current_user_can('manage_options');
            }
        ]
    ]);
}
add_action('rest_api_init', 'vite_demo_register_rest_routes');

// API 处理函数
function vite_demo_get_settings(): WP_REST_Response {
    // 从 WordPress 选项表获取设置
    $settings = [
        'address' => get_option('address', ''),    // 第二参数为默认值
        'api_key' => get_option('api_key', ''),
        'host' => get_option('host', ''),
        'ipfs_host' => get_option('ipfs_host', ''),
        'ipfs_key' => get_option('ipfs_key', '')
    ];

    // 返回 REST API 响应
    return new WP_REST_Response($settings, 200);
}

2. WordPress 钩子系统说明

WordPress 插件开发大量依赖钩子系统，主要使用：

1. 动作钩子（Actions）：

• admin_menu: 用于注册管理菜单
• admin_enqueue_scripts: 用于加载资源文件
• rest_api_init: 用于注册 REST API 端点

2. 过滤器钩子（Filters）：

• style_loader_tag: 用于修改样式标签的输出

构建和启动指南

1. 项目结构说明

推荐的项目结构如下：

wp-content/plugins/vite-demo/
├── dist/                 # 构建输出目录
├── node_modules/         # 依赖包
├── src/                  # 源代码目录
│   ├── components/      # React 组件
│   ├── hooks/          # 自定义 Hooks
│   ├── styles/         # 样式文件
│   └── main.tsx        # 入口文件
├── package.json         # 项目配置
├── plugin.php          # WordPress 插件主文件
├── tsconfig.json       # TypeScript 配置
└── vite.config.ts      # Vite 配置

2. 开发环境配置

2.1 package.json 配置

{
  "name": "vite-demo",
  "private": true,
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "@vitejs/plugin-react": "^4.2.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0"
  }
}

3. 启动和构建流程

3.1 插件激活

1. 确保插件已经正确安装在 WordPress 中：

   • 插件文件应位于 wp-content/plugins/vite-demo/ 目录下
   • 在 WordPress 管理后台进入"插件"页面 (/wp-admin/plugins.php)
   • 找到 "Vite Demo" 插件并点击"启用"

2. 激活后，您应该能在左侧管理菜单中看到 "Vite Demo" 的菜单项

3.2 开发环境启动

1. 启动 WordPress 开发服务器：

# 使用 Local 或其他工具启动 WordPress

2. 启动 Vite 开发服务器：

cd wp-content/plugins/vite-demo
pnpm dev

3. 访问测试：
   • WordPress 管理后台：http://localhost:8889/wp-admin
   • 点击左侧菜单中的 "Vite Demo" 进入插件页面
   • Vite 开发服务器：http://localhost:4200

3.3 生产环境构建

1. 执行构建命令：

pnpm build

2. 构建完成后，dist 目录会生成以下文件：

   • manifest.json：资源映射文件
   • assets/：打包后的 JS、CSS 和其他静态资源

3. 验证部署：

   • 重新访问插件页面，确认资源加载正常
   • 检查控制台是否有报错信息
   • 测试插件功能是否正常运行

4. 开发调试技巧

4.1 开发环境热更新

在 src/main.tsx 中添加热更新支持：

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./index.css";

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

// 启用热更新
if (import.meta.hot) {
  import.meta.hot.accept();
}

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

4.2 调试工具配置

1. 安装 React Developer Tools 浏览器插件

2. 在 vite.config.ts 中添加源码映射配置：

export default defineConfig({
  // ... 其他配置 ...
  build: {
    sourcemap: true, // 启用源码映射
    // ... 其他构建配置 ...
  },
});

4.3 开发环境与生产环境切换

在 plugin.php 中，我们已经通过 WP_DEBUG 常量来区分环境：

$is_dev = defined('WP_DEBUG') && WP_DEBUG;

可以在 wp-config.php 中设置：

// 开发环境
define('WP_DEBUG', true);

// 生产环境
define('WP_DEBUG', false);

参考资料：

• Vite 后端集成指南
• How to use WordPress React components for plugin pages