问题背景与根源分析
当Laravel项目在本地开发环境（如Laravel Valet、Laragon、XAMPP等）中运行时，其内部链接通常工作正常。然而，一旦将项目部署到共享主机（例如000webhost），用户可能会遇到所有非根路径的链接都返回“Page Not Found - Error 404”的错误。这通常是由于服务器未能正确处理Laravel框架的URL重写机制导致的。
Laravel框架采用“单一入口”模式，所有请求都应通过public/index.php文件进行处理。为了实现这一目标，Laravel依赖于Apache服务器的mod_rewrite模块来将友好的URL（例如/posts/1）重写为内部路径，并最终指向index.php。在共享主机环境中，如果.htaccess文件配置不当，或者mod_rewrite模块未启用或配置有误，服务器就无法识别这些友好的URL，从而导致404错误。
解决方案：配置.htaccess文件
解决此问题的关键是在Web服务器的根目录（通常是public_html或与你的Laravel public目录对应的路径）放置一个正确的.htaccess文件。这个文件将指示Apache服务器如何处理传入的请求，确保它们被Laravel的index.php文件正确处理。
以下是适用于大多数Laravel项目在共享主机上运行的.htaccess配置：
<IfModule mod_rewrite.c>
<IfModule mod_negotiation.c>
Options -MultiViews
</IfModule>
RewriteEngine On
# Redirect Trailing Slashes If Not A Folder...
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)/$ /$1 [L,R=301]
# Handle Front Controller...
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]
# Handle Authorization Header
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>.htaccess配置详解
让我们逐行分析上述.htaccess文件的作用：
- <IfModule mod_rewrite.c>: 这是一个条件块，确保只有在Apache的mod_rewrite模块启用时，内部的规则才会被应用。这是非常重要的，因为如果模块未启用，这些规则会导致服务器错误。
- <IfModule mod_negotiation.c> 和 Options -MultiViews: MultiViews选项是Apache mod_negotiation模块的一部分，它允许服务器在请求一个文件时，自动查找具有不同扩展名的文件（例如，请求example可能会找到example.php）。对于Laravel这种依赖精确URL路由的框架，MultiViews可能会干扰其路由机制，因此通常需要禁用它。
- RewriteEngine On: 开启URL重写引擎，这是所有重写规则生效的前提。
- RewriteCond %{REQUEST_FILENAME} !-d: 这是一个重写条件。它检查当前请求的文件名是否不是一个目录。
- *`RewriteRule ^(.)/$ /$1 [L,R=301]`**: 如果请求的URL以斜杠结尾且不是一个实际的目录，这条规则会移除末尾的斜杠并进行301永久重定向。这有助于保持URL的规范化，避免重复内容。
- RewriteCond %{REQUEST_FILENAME} !-d 和 RewriteCond %{REQUEST_FILENAME} !-f: 这两个条件是核心。它们检查当前请求的文件名是否不是一个实际的目录（-d）且不是一个实际的文件（-f）。这意味着如果请求的URL不对应服务器上的任何现有文件或目录，那么它就应该被Laravel处理。
- RewriteRule ^ index.php [L]: 这是主要的重写规则。如果前面的条件都满足，它会将所有请求重写到index.php文件。[L]标志表示这是最后一条规则，停止进一步的重写处理。
- *RewriteCond %{HTTP:Authorization} . 和 `RewriteRule . - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]**: 这两行处理HTTP授权头。某些情况下，Apache可能会在内部清除Authorization头，导致API认证失败。这些规则确保Authorization`头被正确传递给PHP应用程序。
部署步骤与注意事项
-
创建或编辑.htaccess文件:
- 在你的本地Laravel项目的public目录下，确保存在一个名为.htaccess的文件。如果不存在，请创建一个。
- 将上述代码复制并粘贴到这个.htaccess文件中。
-
上传到共享主机:
使用FTP客户端（如FileZilla）或主机提供的文件管理器，连接到你的共享主机。
导航到你的网站根目录。对于000webhost，通常是public_html。
将你的Laravel项目的内容（而不是整个项目文件夹）上传到public_html。特别地，Laravel的public文件夹内的所有内容（包括index.php和刚刚配置的.htaccess）应该直接位于public_html下。其他Laravel项目文件夹（如app, bootstrap, vendor等）应该放在public_html的上一级目录或一个非公开可访问的目录中。
重要提示: 如果你的主机要求所有文件都在public_html下，那么你需要调整Laravel的index.php文件，使其能够正确加载位于public_html内的其他Laravel核心文件。这通常涉及修改index.php中对../vendor/autoload.php和../bootstrap/app.php的路径引用。例如，如果所有内容都在public_html下，则可能需要将../移除或替换为正确的相对路径。
-
标准部署结构示例 (推荐):
/ ├── my_laravel_app_root/ <-- 这是你Laravel项目的所有文件（除了public内容） │ ├── app/ │ ├── bootstrap/ │ ├── config/ │ ├── ... │ └── vendor/ ├── public_html/ <-- 这是Web服务器的公开根目录 │ ├── .htaccess <-- 放置上述代码 │ ├── index.php <-- Laravel的入口文件 │ ├── css/ │ ├── js/ │ └── ... (public资产)
在这种结构下，你需要编辑public_html/index.php来指向my_laravel_app_root中的vendor/autoload.php和bootstrap/app.php。
-
修改public_html/index.php中的路径：
// Original: // require __DIR__.'/../vendor/autoload.php'; // $app = require_once __DIR__.'/../bootstrap/app.php'; // Modified (assuming my_laravel_app_root is sibling to public_html): require __DIR__.'/../my_laravel_app_root/vendor/autoload.php'; $app = require_once __DIR__.'/../my_laravel_app_root/bootstrap/app.php';
-
-
清除Laravel缓存:
- 部署后，通过SSH或主机提供的终端运行以下命令（如果主机支持）：
php artisan cache:clear php artisan config:clear php artisan route:clear php artisan view:clear
- 如果无法SSH访问，可以临时在public/index.php（或public_html/index.php）中添加一行代码来执行这些命令，访问一次后立即删除。
// 在 index.php 文件的顶部添加（临时用，用完删除） // Artisan::call('cache:clear'); // Artisan::call('config:clear'); // Artisan::call('route:clear'); // Artisan::call('view:clear');
- 部署后，通过SSH或主机提供的终端运行以下命令（如果主机支持）：
-
检查文件权限:
- 确保storage和bootstrap/cache目录及其子目录具有Web服务器用户（通常是www-data或nobody）的写入权限（通常是775或777）。
总结
解决Laravel项目在共享主机上链接失效的404问题，核心在于正确配置.htaccess文件，以确保Apache服务器能够将所有非文件/目录的请求重写到Laravel的index.php前端控制器。同时，合理的项目文件结构和正确的Laravel缓存清理也是确保应用正常运行的关键。通过遵循上述步骤，可以有效解决大多数此类部署问题，使Laravel应用在共享主机环境中稳定运行。
