Laravel 8迁移Vite后，部署时因流量触发manifest缺失500错误

针对部署过程中manifest.json生成瞬间有请求触发500错误的问题，提供以下几种实用解决方案：

1. 临时目录构建后原子替换 #

在部署脚本中先在临时目录完成Vite构建，再将构建产物一次性同步到项目的public/build目录，避免构建过程中出现文件缺失的窗口。

部署脚本示例：

# 创建临时构建目录
mkdir -p /tmp/vite-build
# 复制必要配置文件到临时目录
cp package.json package-lock.json vite.config.js /tmp/vite-build/
cd /tmp/vite-build

# 安装依赖并构建
npm ci
npm run prod

# 原子替换项目的build目录（rsync保证增量替换且无中断）
rsync -av --delete /tmp/vite-build/public/build/ /home/forge/<myproject>/public/build/

# 清理临时文件
cd /home/forge/<myproject>
rm -rf /tmp/vite-build

2. 捕获Manifest缺失异常，返回备用资源 #

自定义Vite资源引用的辅助函数，捕获manifest.json不存在的异常，返回预定义的静态资源，避免抛出500错误。

1. 在项目根目录创建app/helpers.php文件，添加自定义函数：

<?php

function safe_vite(string $entry)
{
    try {
        return \Illuminate\Support\Facades\Vite::asset($entry);
    } catch (\Exception $e) {
        // 返回备用静态资源路径，根据实际项目调整
        return match ($entry) {
            'resources/js/app.js' => '/static/js/app.js',
            'resources/css/app.css' => '/static/css/app.css',
            default => $entry,
        };
    }
}

2. 在composer.json中自动加载该文件：

"autoload": {
    "files": [
        "app/helpers.php"
    ]
}

3. 执行composer dump-autoload生效，然后在视图中替换原有的@vite指令：

<script src="{{ safe_vite('resources/js/app.js') }}"></script>
<link rel="stylesheet" href="{{ safe_vite('resources/css/app.css') }}">

3. 保留旧build目录直到新构建完成 #

部署时先备份旧的build目录，完成新构建后再删除旧目录，确保构建过程中旧的manifest.json始终可用。

部署脚本示例：

cd /home/forge/<myproject>

# 备份旧build目录（如果存在）
if [ -d public/build ]; then
    mv public/build public/build-old
fi

# 安装依赖并构建新资源
npm ci
npm run prod

# 删除旧备份
rm -rf public/build-old

4. 启用部署维护模式 #

利用Laravel的维护模式，在部署期间拦截所有用户请求，返回友好的维护页面，避免构建过程中处理请求。

部署脚本示例：

cd /home/forge/<myproject>

# 开启维护模式，设置重试间隔和提示信息
php artisan down --message="网站正在更新，1分钟后重试" --retry=60

# 拉取代码、安装依赖、构建资源、执行迁移
git pull origin main
composer install --no-dev --optimize-autoloader
npm ci
npm run prod
php artisan migrate --force

# 关闭维护模式
php artisan up

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