Laravel+Vue+InertiaJS中sail npm run dev白屏及热更新优化需求

问题详情 #

• 开发环境：Laravel + Vue + InertiaJS，基于Laravel Sail Docker容器
• 异常现象：执行sail up -d启动容器后，运行sail npm run dev时浏览器显示空白白屏；但执行sail npm run build完成生产构建后，应用可正常访问。每次修改代码都需要重新构建，耗时过长，需要实现dev模式正常运行并支持热更新。

附docker-compose.yml相关配置 #

build:
    context: ./vendor/laravel/sail/runtimes/8.2
    dockerfile: Dockerfile
    args:
        WWWGROUP: '${WWWGROUP}'
image: sail-8.2/app
extra_hosts:
    - 'host.docker.internal:host-gateway'
ports:
    - '${APP_PORT:-80}:80'
    - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
environment:
    WWWUSER: '${WWWUSER}'
    LARAVEL_SAIL: 1
    XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
    XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
    IGNITION_LOCAL_SITES_PATH: '${PWD}'
volumes:
    - '.:/var/www/html'
    - './library/petcheckr-library/resources/js:/var/www/html/resources/js/Petcheckr'
    - './library/xocdr-library/resources/js:/var/www/html/resources/js/Xocdr'
    - './storage/app/public:/var/www/html/public/storage'
networks:
    - petcheckr
depends_on:
    - mariadb
    - redis
    - mailpit
mariadb:
    image: 'mariadb:10'
    ports:
        - '${FORWARD_DB_PORT:-3306}:3306'
    environment:
        MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}'
        MYSQL_ROOT_HOST: '%'
        MYSQL_DATABASE: '${DB_DATABASE}'
        MYSQL_USER: '${DB_USERNAME}'
        MYSQL_PASSWORD: '${DB_PASSWORD}'
        MYSQL_ALLOW_EMPTY_PASSWORD: 'yes'
    volumes:
        - 'sail-mariadb:/var/lib/mysql'
        - './vendor/laravel/sail/database/mysql/create-testing-database.sh:/docker-entrypoint-initdb.d/10-create-testing-database.sh'
    networks:

解决方案 #

1. 核对VITE配置与端口映射 #

• 确保.env文件中VITE_PORT=5173（与docker-compose的端口映射一致），APP_URL设置为你的开发地址（如http://localhost）
• 修改vite.config.js，添加服务器配置允许外部访问并设置热更新主机：

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

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            refresh: true,
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
    server: {
        host: '0.0.0.0', // 允许容器外部访问VITE dev服务器
        port: 5173,
        hmr: {
            host: 'localhost', // 对应APP_URL的域名/IP
        },
    },
});

2. 确认Inertia根模板的脚本引入 #

• 检查resources/views/app.blade.php，确保使用Laravel官方的VITE指令引入脚本，不要手动写死路径：

@vite('resources/js/app.js')
@inertia

3. 清理缓存与重新安装依赖 #

执行以下命令重置依赖和缓存：

sail npm cache clean --force
sail rm -rf node_modules package-lock.json
sail npm install
sail artisan config:clear
sail artisan view:clear

4. 检查Docker卷映射与文件权限 #

• 进入容器验证映射文件是否存在：sail bash，然后执行ls /var/www/html/resources/js/Petcheckr，确认第三方库文件已正确映射
• 修复文件权限：sail chown -R sail:sail /var/www/html

5. 查看浏览器控制台定位错误 #

打开浏览器开发者工具（F12），查看Console标签的JS错误，以及Network标签的资源加载失败记录，这些信息能直接定位白屏原因（比如VITE dev服务器脚本无法加载、组件报错等）

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