解决 Laravel 项目在共享主机上链接失效的 404 错误

理解 Laravel 路由与共享主机环境的挑战

Laravel 框架采用“前端控制器”模式，这意味着所有 HTTP 请求都应通过位于项目 public 目录下的 index.php 文件进行处理。index.php 负责加载框架核心，解析请求的 URL，并将其路由到相应的控制器或闭包函数。在本地开发环境中，通常由 PHP 内置服务器、Nginx 或 Apache 配置来确保所有请求都正确地重定向到 index.php。

然而，当 Laravel 项目部署到某些共享主机环境时，服务器的默认配置可能无法识别这种重写规则，导致除了根 URL (/) 之外的所有内部链接都返回 404 错误。这是因为服务器在文件系统中找不到与请求 URL 直接对应的物理文件或目录，而没有将请求转发给 index.php 进行动态处理。

解决方案：配置 .htaccess 文件

解决此问题的关键在于为 Apache 服务器配置正确的 URL 重写规则。这通常通过在网站的文档根目录（在 000webhost 这样的主机上通常是 public_html 目录）中创建一个或修改现有的 .htaccess 文件来实现。此文件将指示 Apache 如何处理传入的请求，确保它们被 Laravel 的 index.php 文件捕获。

以下是适用于 Laravel 项目的 .htaccess 文件内容：

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

RewriteEngine On

# 移除尾部斜杠，如果不是目录的话
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)/$ /$1 [L,R=301]

# 处理前端控制器：将所有非文件/非目录请求重写到 index.php
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]

# 处理授权头部
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>

.htaccess 文件内容解析：

1. : 这是一个条件块，确保只有在 Apache 服务器启用了 mod_rewrite 模块时，其中的规则才会被应用。这是 URL 重写功能的基础。
2. Options -MultiViews : MultiViews 是 Apache 的一个功能，它允许服务器尝试自动查找与请求文件名匹配的文件（例如，请求 example 但存在 example.php 或 example.html）。禁用此选项可以防止与 Laravel 的路由系统发生冲突，确保请求完全由 .htaccess 规则控制。
3. RewriteEngine On: 显式开启 Apache 的 URL 重写引擎。
4. RewriteCond %{REQUEST_FILENAME} !-d 和 *`RewriteRule ^(.)/$ /$1 [L,R=301]`**:
   • RewriteCond %{REQUEST_FILENAME} !-d: 这是一个条件，表示只有当请求的 URI 不是一个实际存在的目录时，才应用后续的规则。
   • RewriteRule ^(.*)/$ /$1 [L,R=301]: 这条规则会移除 URL 末尾多余的斜杠（例如 example.com/about/ 会被重定向到 example.com/about）。[L] 表示这是最后一条规则，[R=301] 表示执行一个永久重定向。
5. RewriteCond %{REQUEST_FILENAME} !-d 和 RewriteCond %{REQUEST_FILENAME} !-f 和 RewriteRule ^ index.php [L]:
   • RewriteCond %{REQUEST_FILENAME} !-d: 条件，如果请求的 URI 不是一个实际存在的目录。
   • RewriteCond %{REQUEST_FILENAME} !-f: 条件，如果请求的 URI 不是一个实际存在的文件。
   • RewriteRule ^ index.php [L]: 这是 Laravel 路由的核心。如果上述两个条件都满足（即请求的 URI 既不是文件也不是目录），则将所有请求重写到 index.php。^ 匹配任何请求，[L] 表示这是最后一条重写规则。
6. RewriteCond %{HTTP:Authorization} . 和 *`RewriteRule . - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]`**:
   • 这两行规则确保 HTTP 请求中的 Authorization 头部信息能够被正确地传递给 PHP 应用程序。这对于处理 API 请求中的认证令牌（如 Bearer Token）至关重要。

实施步骤

1. 准备 Laravel 项目文件： 通常，为了在共享主机上部署 Laravel，你需要将 Laravel 项目 public 目录下的所有内容（包括 index.php、.htaccess 文件、CSS/JS/图片等静态资源）直接上传到主机的文档根目录（例如 public_html）。项目的其余部分（app、bootstrap、vendor 等）应该上传到 public_html 的上一级目录或同级目录，以保证其安全性和私密性。
2. 创建或修改 .htaccess 文件：
   • 在你的本地 Laravel 项目的 public 目录下，通常已经有一个 .htaccess 文件。确认其内容与上述示例一致。
   • 如果你的 public_html 目录中没有 .htaccess 文件，或者其内容不正确，请创建一个新文件并粘贴上述代码。
   • 如果已经存在 .htaccess 文件，请备份原有内容，然后替换为上述代码。
3. 上传文件： 使用 FTP 客户端或主机提供的文件管理器，将修改后的 .htaccess 文件上传到你的网站根目录（例如 public_html）。
4. 清除 Laravel 缓存（可选但推荐）： 部署后，清除 Laravel 应用程序的配置、路由和视图缓存通常是一个好习惯，以确保所有更改生效。如果你的主机支持 SSH 访问，可以运行：

   php artisan config:clear
   php artisan route:clear
   php artisan view:clear

   登录后复制

   如果不支持 SSH，可能需要手动删除 bootstrap/cache 目录下的缓存文件，或者在 public/index.php 中临时添加 Artisan::call('cache:clear'); 等代码（完成后务必删除）。

注意事项

• mod_rewrite 模块： 确保你的共享主机已启用 Apache 的 mod_rewrite 模块。大多数现代主机默认都会启用，但如果问题依然存在，请联系你的主机提供商确认。
• 文件权限： 确保 .htaccess 文件的权限设置正确，通常是 644 或 664，以允许服务器读取。
• 根目录结构： 上述解决方案假设你已将 Laravel 项目的 public 目录内容直接放在了网站的文档根目录（如 public_html）。如果你的部署结构不同，例如 public_html/laravel/public，那么 .htaccess 文件可能需要放置在 public_html 下，并且可能需要调整 Laravel 的 index.php 来正确加载框架核心。
• 其他服务器类型： 如果你的主机使用的是 Nginx 而非 Apache，那么 .htaccess 文件将不起作用。Nginx 需要在其配置文件中进行类似的 URL 重写配置。

总结

通过在共享主机的文档根目录中正确配置 .htaccess 文件，可以有效解决 Laravel 项目部署后内部链接 404 的问题。这个 .htaccess 文件确保了所有非文件、非目录的请求都被重定向到 index.php，从而让 Laravel 的路由系统能够正常工作。理解其背后的原理和每个规则的作用，有助于在遇到类似问题时进行快速排查和解决。

以上就是解决 Laravel 项目在共享主机上链接失效的 404 错误的详细内容，更多请关注php中文网其它相关文章！