Laravel项目构建资源加载Bootstrap失败 npm run dev异常如何解决

执行npm run dev时无报错直接崩溃、不输出编译成功提示，按以下顺序排查：

• 基础依赖修复
  绝大多数静默崩溃都是依赖安装损坏、版本不匹配导致，优先执行全量依赖重装：

  # 删除现有依赖文件和锁文件
  rm -rf node_modules package-lock.json
  # 强制清理npm缓存
  npm cache clean --force
  # 重新安装全量依赖
  npm install
  

  重装完成后核对Node版本：Laravel 8+要求Node版本≥16，优先选择18.x、20.x这类LTS版本，避免使用非LTS的最新版Node，兼容问题极易触发无提示崩溃。
  确认Bootstrap相关依赖已正确安装：手动构建引入Bootstrap需要额外安装两个依赖，缺包也会导致编译中断：

  npm install bootstrap @popperjs/core --save-dev
  

  同时核对资源入口文件的引入代码：

  resources/js/app.js 中需添加 import 'bootstrap';
resources/css/app.css 中需添加 @import "bootstrap";

• 编译配置排查
  先确认构建配置文件无异常：

  • 使用Vite的新版Laravel（9.x及以上默认）：检查vite.config.js，临时删除自定义的server、https配置，排查是否为端口冲突、证书配置错误导致进程退出，默认配置即可正常完成编译。
  • 使用Laravel Mix的旧版项目：检查webpack.mix.js，不要重复配置Bootstrap的独立编译规则，保持默认的js、css编译规则即可正常处理引入的第三方库代码。
    执行带调试参数的编译命令查看隐藏报错，默认日志会吞掉底层错误：

  # Vite项目执行
  npm run dev -- --verbose
  # Mix项目执行
  npm run dev -- --debug
  

  调试模式下会输出完整运行日志，端口占用、文件权限不足、路径不存在这类之前被隐藏的问题会直接打印到终端。

• 特殊场景问题处理

  • 权限异常：如果是Linux/macOS环境，之前用过sudo执行npm命令会导致node_modules目录权限归属root，当前运行用户无读写权限时会直接触发进程崩溃，执行sudo chown -R $USER:$USER 你的项目根目录路径修复权限即可，禁止后续用sudo执行npm相关命令。
  • 端口占用：Vite默认占用5173端口、旧版Mix默认占用8080端口，端口被其他本地服务、Docker容器占用时，部分版本的构建工具不会输出报错直接退出，可以在配置文件中手动指定空闲端口重试。
  • 脚本配置篡改：打开package.json核对scripts字段的dev命令，Vite项目默认配置为"dev": "vite"，Mix项目默认配置为"dev": "npm run development", "development": "mix"，如果配置被改动直接改回默认值即可。

终端运行异常状态参考：

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