基于Vite+Docker+Pug的WordPress开发：PHP自动刷新问题解决方案

以下是针对你的场景的具体排查和修复步骤：

1. 修正liveReload插件的监听路径 #

确保vite-plugin-live-reload的监听范围完全覆盖生成的PHP文件路径，尤其是Docker映射后的本地目录。比如你的主题在本地./wp-content/themes/my-theme/下，配置要写精确：

import liveReload from 'vite-plugin-live-reload'

export default {
  plugins: [
    liveReload([
      './wp-content/themes/my-theme/**/*.php', // 监听主题下所有PHP文件
      './wp-content/themes/my-theme/src/**/*.pug' // 可选，直接监听Pug源文件变更
    ])
  ],
  // 其他Vite配置
}

注意：Vite运行在本地，所以要监听本地的PHP生成路径，不要写容器内的路径。

2. 修复HMR脚本的引入逻辑 #

硬编码Vite地址可能导致Docker容器无法访问本地服务，改用动态适配的方式在functions.php中引入：

function enqueue_vite_dev_scripts() {
    if (defined('WP_ENV') && WP_ENV === 'development') {
        // 针对Docker环境，用host.docker.internal访问宿主机的Vite服务
        $vite_server = 'http://host.docker.internal:5173';
        // 如果是本地直接运行WordPress，替换成http://localhost:5173
        
        wp_enqueue_script('vite-hmr', $vite_server . '/@vite/client', [], null, true);
        // 若有自定义JS入口，同时引入
        wp_enqueue_script('theme-main', $vite_server . '/src/main.js', [], null, true);
    }
}
add_action('wp_enqueue_scripts', 'enqueue_vite_dev_scripts');

同时在wp-config.php中添加环境定义：

define('WP_ENV', 'development');
define('WP_DEBUG', true);
define('WP_CACHE', false);

3. 配置Docker网络连通性 #

如果WordPress在容器内，需要让容器能访问宿主机的Vite服务：
在docker-compose.yml的wordpress服务中添加：

services:
  wordpress:
    # 现有配置...
    extra_hosts:
      - "host.docker.internal:host-gateway"

这个配置让容器可以通过host.docker.internal访问宿主机的服务，避免用固定IP导致的适配问题。

4. 调整Vite的server跨域配置 #

在vite.config.js中添加server配置，允许WordPress域名的跨域请求：

export default {
  server: {
    host: '0.0.0.0', // 允许外部设备访问Vite服务
    port: 5173,
    cors: {
      origin: 'http://localhost:8000', // 你的WordPress访问地址（Docker映射的端口）
      credentials: true
    }
  },
  // 其他配置
}

5. 验证文件变更的监听触发 #

手动修改一个生成的PHP文件，查看Vite控制台是否输出LiveReloading...的日志。如果没有，说明监听路径有误，检查路径是否匹配本地文件结构；如果有日志但页面不刷新，检查浏览器控制台是否有HMR相关的报错（比如跨域、连接失败）。

6. 禁用WordPress缓存 #

开发环境下务必禁用所有缓存：

• 关闭WP_DEBUG以外的缓存插件
• 确保wp-config.php中WP_CACHE设为false
• 开启浏览器开发者工具的「禁用缓存」选项

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