Vite Manifest 文件未找到错误解决方案

问题概述

当在 Laravel 项目中使用 Vite 时，开发环境一切正常，但在生产环境（特别是 cPanel 共享主机）上部署时出现 "Vite manifest not found" 错误。

错误原因分析

这个错误通常发生在以下几种情况：

• Vite 构建过程未正确执行，缺少 manifest.json 文件
• 文件权限问题导致无法读取 manifest 文件
• Node.js 版本不兼容
• 项目文件结构在部署过程中发生变化
• 公共目录路径配置不正确

解决方案

1. 基本构建流程

首先确保执行正确的构建流程：

# 安装依赖
npm install

# 构建生产版本
npm run build

重要提示

确保在部署前运行 npm run build 命令，这会生成 public/build 目录和 manifest.json 文件。

2. 处理文件结构变更

当 cPanel 服务器要求将 public 目录内容移动到 public_html 时：

cPanel 文件结构调整示例

- home
    - public_html          # 所有公开访问的文件
        - index.php
        - build/           # Vite 构建文件应放在这里
        - ...
    - cart_shop           # 应用根目录
        - app/
        - resources/
        - ...

在这种情况下，需要调整 Vite 配置：

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',
            // 指定公共目录路径
            publicDirectory: '../../public_html'
        }),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
    // 确保构建输出到正确位置
    build: {
        outDir: '../../public_html/build',
        manifest: true
    },
});

3. Node.js 版本兼容性

确保使用兼容的 Node.js 版本（推荐 Node.js 16+）：

# 使用 nvm 管理 Node.js 版本
nvm install 18
nvm use 18

版本建议

• Laravel 9: Node.js 16+
• Laravel 10: Node.js 18+
• 最新版本: Node.js 20+

4. 文件权限问题

确保 Web 服务器有权限访问构建文件：

# 设置正确的文件权限
chown -R www-data:www-data public/build/
chmod -R 755 public/build/

5. Laravel 配置调整

在 AppServiceProvider.php 中自定义构建目录：

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Vite;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // 自定义 Vite 构建目录
        Vite::useBuildDirectory('.'); // 相对于 public 目录
    }
}

6. 部署工作流优化

创建自动化部署脚本：

#!/bin/bash
# deploy.sh

# 安装依赖
npm install

# 构建项目
npm run build

# 同步文件到 public_html（根据实际结构调整）
rsync -av --delete public/build/ ../public_html/build/
rsync -av public/index.php ../public_html/
rsync -av public/.htaccess ../public_html/

echo "部署完成"

特殊情况处理

cPanel 共享主机部署

对于 cPanel 共享主机，可能需要手动处理构建文件：

1. 本地运行 npm run build
2. 将生成的 build 文件夹上传到服务器
3. 确保 build 文件夹位于正确的路径：
   • 如果应用根目录有 public 文件夹，放在 public/build
   • 如果使用 public_html，放在 public_html/build

Git 忽略文件问题

检查 .gitignore 文件，确保没有忽略必要的构建文件：

# 确保不被忽略
!/public/build
!/public/build/manifest.json

故障排除

如果问题仍然存在，尝试以下步骤：

1. 清除缓存和重新安装依赖：

   rm -rf node_modules
   rm package-lock.json
   npm install
   npm run build

2. 检查构建过程是否有错误：

   npm run build -- --debug

3. 验证 manifest 文件是否生成：

   ls -la public/build/ | grep manifest

总结

"Vite manifest not found" 错误通常由构建流程不完整、路径配置错误或环境兼容性问题引起。通过确保正确的构建流程、调整路径配置和使用兼容的 Node.js 版本，可以解决大多数相关问题。

生产环境提醒

永远不要在生产服务器上运行 npm run dev，这会导致性能问题和安全隐患。始终使用 npm run build 生成生产版本。