Laravel执行npm run dev编译Sass文件卡在APP_URL如何解决

问题复现 #

已安装laravel/ui与Node.js相关依赖，执行npm run dev命令编译Sass文件时，进程停在APP_URL输出环节无后续响应，终端输出内容如下：

> dev
> vite
Port 3000 is in use, trying another one...
vite v2.9.14 dev server running at:
> Local: http://localhost:3001/
> Network: use `--host` to expose
ready in 933ms.
Laravel v9.19.0
> APP_URL: http://localhost

输出上述内容后进程无后续动作，无法完成前端资源编译。

核心原因 #

这个状态不是进程卡死，是Laravel 9默认替换前端构建工具为Vite后的正常表现：

• 旧版Laravel使用Mix时，npm run dev执行完单次编译就会退出进程
• Vite模式下npm run dev默认启动常驻的热更新开发服务器，输出到APP_URL那一行就代表服务已经启动完成，会持续在后台监听前端文件变化，不会自动退出，很容易被误以为是卡住。

对应处理方案 #

根据实际使用场景选择操作即可：

• 本地开发需要热更新：不要关闭当前终端窗口，直接访问项目页面即可，修改Sass、JS等前端文件时Vite会自动触发增量编译，页面实时同步变更，无需额外操作。
• 需要一次性编译资源、执行完自动退出：不要运行npm run dev，改用npm run build命令，该命令会一次性完成所有前端资源的打包压缩，输出到public目录后自动结束进程。
• 启动dev服务后修改文件无反应、页面无法加载资源：先检查vite.config.js配置是否正确引入了laravel/ui对应的Sass、JS入口文件，可手动固定服务端口避免自动切换端口带来的连接异常，配置参考：

// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            // 确认入口路径和实际项目文件路径一致
            input: [
                'resources/sass/app.scss',
                'resources/js/app.js',
            ],
            refresh: true,
        }),
    ],
    server: {
        port: 3000, // 提前确认该端口未被其他程序占用
        hmr: {
            host: 'localhost'
        }
    }
});

调整配置后先执行npm run build验证单次编译流程正常，再启动dev服务即可。

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