Laravel默认集成Vite后执行npm run dev启动开发环境失败如何解决

Taylor Otwell宣布新版Laravel项目将默认预装并使用Vite作为前端构建工具，但新建项目后无法正常运行开发环境的npm run dev命令。
复现操作流程：

• 新建Laravel项目
• 安装支持SSR、teams多团队功能的Laravel JetStream
• 执行npm install完成依赖安装
• 运行npm run dev持续抛出报错，无法正常编译前端资源，访问启动后的本地链接页面显示异常
• 直接在终端执行vite命令同样报错

相关报错截图：

当前全新安装项目的package.json配置如下：

{
    "private": true,
    "scripts": {
        "dev": "vite",
        "build": "vite build && vite build --ssr"
    },
    "devDependencies": {
        "@inertiajs/inertia": "^0.11.0",
        "@inertiajs/inertia-vue3": "^0.6.0",
        "@inertiajs/progress": "^0.2.7",
        "@inertiajs/server": "^0.1.0",
        "@tailwindcss/forms": "^0.5.2",
        "@tailwindcss/typography": "^0.5.2",
        "@vitejs/plugin-vue": "^2.3.3",
        "@vue/server-renderer": "^3.2.31",
        "autoprefixer": "^10.4.7",
        "axios": "^0.25",
        "laravel-vite-plugin": "^0.2.1",
        "lodash": "^4.17.19",
        "postcss": "^8.4.14",
        "tailwindcss": "^3.1.0",
        "vite": "^2.9.11",
        "vue": "^3.2.31"
    }
}

该问题属于Laravel切换Vite作为默认构建工具早期版本的典型兼容问题，核心诱因有三点：

1. Node版本不满足要求：Vite 2.9+ 要求Node.js版本至少为14.18.0，本地Node版本低于该阈值时会直接出现语法报错、启动失败
2. laravel-vite-plugin版本bug：项目中使用的laravel-vite-plugin@0.2.1属于早期测试版本，在搭配Jetstream Inertia SSR栈、多团队功能的场景下，存在入口路径解析错误、SSR资源识别异常的已知问题
3. 依赖版本不匹配：Vite主版本和对应的Vue插件、laravel插件版本未做对齐，部分依赖安装时存在锁文件冲突，导致运行时调用方法不存在

按照以下步骤逐一排查修复：

1. 校验本地Node版本
   终端执行node -v查看当前Node版本，若版本低于14.18.0，先升级Node.js到16.x/18.x的LTS长期支持版本，升级完成后重启终端再进行后续操作。
2. 清理旧依赖缓存
   进入项目根目录，执行对应命令删除旧的依赖目录和锁文件：

   # macOS/Linux系统执行
   rm -rf node_modules package-lock.json
   
   # Windows系统cmd环境执行
   rmdir /s /q node_modules
   del package-lock.json
   

3. 升级依赖到兼容稳定版本
   执行命令升级存在bug的构建相关依赖：

   npm install vite@^3.2.0 laravel-vite-plugin@^0.6.1 @vitejs/plugin-vue@^3.0.0 --save-dev
   

   若安装时出现peer依赖冲突，可在命令末尾追加--legacy-peer-deps参数。
4. 校验vite配置文件
   打开项目根目录的vite.config.js，确认配置符合Jetstream+SSR的要求，参考配置如下：

   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',
               ssr: 'resources/js/ssr.js',
               refresh: true,
           }),
           vue({
               template: {
                   transformAssetUrls: {
                       base: null,
                       includeAbsolute: false,
                   },
               },
           }),
       ],
   });
   

5. 重新安装依赖并启动服务

   npm install
   npm run dev
   

启动成功后清除浏览器缓存再访问本地地址即可正常加载前端资源。若仍存在页面加载异常，检查.env文件中APP_URL配置和实际访问的地址、端口保持一致。

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