Laravel 12部署Filament 3.2到Debian 12 VPS后除首页外所有路由返回404的排查求助

开发者阿泽

2026-4-8

看起来你遇到了Laravel部署到Apache环境下典型的URL重写类问题，结合你已经执行的缓存清理、存储链接创建等操作，我帮你梳理几个关键的排查方向，按顺序尝试应该能定位到问题：

检查Apache的mod_rewrite模块是否启用
Laravel的路由依赖Apache的mod_rewrite模块来实现URL重写，如果这个模块没开启，除了首页以外的路由都会返回404。执行以下命令启用并重启Apache：
```
sudo a2enmod rewrite
sudo systemctl restart apache2
```

修正Apache配置中的Directory权限规则
你当前的Apache配置里，/var/www/目录的AllowOverride all规则并没有覆盖到你的实际文档根目录/var/www/html/public，需要在000-default.conf的<VirtualHost>块内添加针对public目录的权限配置：

<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html/public
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined

    # 添加这部分配置
    <Directory /var/www/html/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

修改完成后重启Apache：sudo systemctl restart apache2

确认public目录下的.htaccess文件存在且配置正确
这个文件是Laravel实现URL重写的核心配置，检查/var/www/html/public/.htaccess是否存在，如果没有，复制Laravel默认的内容到该文件：

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Handle Authorization Header
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} (.+)/$
    RewriteRule ^ %1 [L,R=301]

    # Send Requests To Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

同时确保文件权限正确，让Apache可以读取：

sudo chmod 644 /var/www/html/public/.htaccess
sudo chown www-data:www-data /var/www/html/public/.htaccess

检查项目文件的权限与所属用户
Laravel需要对storage和bootstrap/cache目录有写入权限，同时整个项目的文件所属用户应该是Apache的运行用户www-data，执行以下命令修正：
```
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html
sudo chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
```
排查路由缓存的问题
你执行了php artisan route:cache，但要注意：闭包路由（比如你添加的/test闭包路由）无法被路由缓存，缓存后这类路由会直接失效。先清理路由缓存再测试：
```
php artisan route:clear
```
如果后续需要使用路由缓存，所有路由都需要指向控制器方法，而不能用闭包。
确认生产环境依赖是否完整安装
如果你是直接复制本地项目文件到VPS，可能vendor目录缺失或依赖不兼容，在VPS的项目根目录执行以下命令安装生产环境依赖：
```
cd /var/www/html
composer install --optimize-autoloader --no-dev
```
查看Apache错误日志定位具体问题
以上步骤如果都没解决，直接查看Apache的错误日志，里面会有更详细的错误信息：
```
sudo cat /var/log/apache2/error.log
```
比如可能会提示权限不足、重写规则错误、PHP模块缺失等具体问题。

内容来源于stack exchange