远程服务器上Laravel 10 + Vite HMR自动重载后空白页问题求助

问题场景 #

远程服务器运行Laravel 10和Vite Dev Server，本地通过VS Code的SFTP扩展同步文件。编辑Blade模板后，SFTP同步成功，但Vite触发多次页面重载，有时页面变成空白，无法渲染最新模板。

现有配置 #

Vite配置文件 #

import { build, defineConfig, splitVendorChunkPlugin } from 'vite';
import laravel from 'laravel-vite-plugin';
import inject from "@rollup/plugin-inject";

export default defineConfig({
    server: {
        hmr: {
            host: 'MY_IP',
        }
    },
    build: {
        sourcemap: 'hidden',
        emptyOutDir: true,
        rollupOptions: {
            output: {
                assetFileNames: (assetInfo) => {
                    let extType = assetInfo.name.split('.').at(1);
                    if (/png|jpe?g|svg|gif|tiff|bmp|ico/i.test(extType)) {
                    extType = 'images';
                    } else if (/woff|woff2|otf|eot|ttf/.test(extType)) {
                        extType = "fonts";
                    }
                    return `assets/${extType}/[name]-[hash][extname]`;
                },
                chunkFileNames: 'assets/js/[name]-[hash].js',
                entryFileNames: 'assets/js/[name]-[hash].js',
            },
        },
    },
    plugins: [
        splitVendorChunkPlugin(),
        inject({
            $: 'jquery',
            jQuery: 'jquery',
        }),
        laravel({
            input: ['resources/scss/styles.scss', 'resources/js/app.js'],
            refresh: true,
        }),
    ]
});

启动命令 #

vite --debug --host

关键日志片段 #

11:09:20 AM [vite] page reload resources/views/trader_add/index.blade.php (x6)
  vite:hmr [no modules matched] resources/views/trader_add/index.blade.php +1ms
  vite:hmr [file change] resources/views/trader_add/index.blade.php +91ms
11:09:20 AM [vite] page reload resources/views/trader_add/index.blade.php (x7)
  vite:hmr [no modules matched] resources/views/trader_add/index.blade.php +2ms
...
11:09:39 AM [vite] page reload resources/views/trader_add/index.blade.php (x12)
  vite:hmr [no modules matched] resources/views/trader_add/index.blade.php +2ms

问题分析 #

SFTP同步文件时可能触发多次文件变更事件（如先传临时文件再替换原文件），导致Vite重复触发全页重载；同时Blade文件不属于Vite模块依赖，只能触发全页刷新，多次重载可能导致浏览器渲染异常，出现空白页。

解决方案 #

1. 优化SFTP同步策略，减少文件变更事件 #

修改VS Code SFTP扩展配置（.vscode/sftp.json），禁用临时文件同步，直接覆盖远程文件：

"uploadOnSave": true,
"syncMode": "update",
"watcher": {
  "files": "**/*",
  "autoUpload": true,
  "autoDelete": true,
  "usePolling": false,
  "ignored": [".vscode", ".git", "node_modules"]
},
"tempFile": false

2. 调整Vite的refresh配置，添加防抖机制 #

修改Laravel Vite Plugin的refresh选项，指定监听路径并添加防抖，合并短时间内的多次变更事件：

laravel({
    input: ['resources/scss/styles.scss', 'resources/js/app.js'],
    refresh: {
        paths: [
            'resources/views/**/*.blade.php',
            'resources/lang/**/*.php'
        ],
        delay: 300 // 等待300ms后再触发重载，避免重复刷新
    },
}),

3. 改用Laravel原生自动刷新处理Blade变更 #

保留Vite HMR仅处理静态资源，让Laravel负责Blade变更的页面刷新：

• 在根Blade模板中添加自动刷新脚本：

@if(app()->environment('local'))
    <script src="{{ asset('/vendor/laravel-vite/refresh.js') }}"></script>
@endif

• 确保config/app.php中APP_ENV设置为local，Laravel会在Blade文件变更时触发单次页面刷新。

4. 检查HMR网络配置 #

确保远程服务器的HMR端口（默认24678）对外开放，客户端能正常连接：

server: {
    hmr: {
        host: 'MY_IP',
        port: 24678,
        protocol: 'ws',
        clientPort: 24678
    },
    host: '0.0.0.0',
    port: 5173
}

使用反向代理时，需确保代理转发WS请求到Vite的HMR端口。

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