解决PHP项目.htaccess URL重写部署失败：Apache配置指南

1. 问题背景与现象

许多现代php框架和应用（如laravel、symfony等）都采用前端控制器模式，将所有请求路由到单一的index.php文件，并通过.htaccess文件实现url重写，以提供友好的、无扩展名的url。典型的项目结构可能包含一个应用逻辑目录（如/app）、一个公共资源目录（如/public，其中包含index.php和静态资源），以及一个位于项目根目录的.htaccess文件，内容示例如下：

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule (.*) public/index.php/$1 [L]

当此类项目在本地开发环境（如XAMPP、WAMP或Docker）中运行正常，但在部署到生产服务器（如基于Debian Stretch、Plesk Obsidian的Apache服务器）后，却收到“File not found”错误，这通常意味着Apache未能正确解析或执行.htaccess中的重写规则。

2. 核心解决方案：Apache配置检查与调整

解决此类部署问题的关键在于检查并调整Apache服务器的两个核心配置：AllowOverride指令和mod_rewrite模块。

2.1 启用 .htaccess 解析：AllowOverride All

.htaccess文件能否生效，取决于Apache站点配置中AllowOverride指令的设置。默认情况下，为了安全和性能考虑，AllowOverride可能被设置为None，这意味着Apache会忽略目录中的所有.htaccess文件。

要启用.htaccess，需要修改你的Apache虚拟主机配置文件（通常位于/etc/apache2/sites-available/目录下，文件名为your_site.conf或example.com.conf）。在该文件的<Directory>块中，确保包含AllowOverride All指令。

立即学习“PHP免费学习笔记（深入）”；

操作步骤：

1. 定位配置文件：

   • 对于基于Debian的系统，虚拟主机配置文件通常在/etc/apache2/sites-available/。
   • 如果你使用Plesk等面板，可能需要通过面板界面或在/etc/apache2/conf-enabled/或/etc/apache2/sites-enabled/中查找由Plesk生成的配置文件。
   • 找到对应你部署域名的虚拟主机配置文件，例如dev.example.org.conf。

2. 编辑配置文件： 使用文本编辑器（如nano或vim）打开该文件，找到与你的项目DocumentRoot对应的<Directory>块。如果你的项目DocumentRoot指向public目录，那么<Directory>指令也应指向该目录。

   示例配置：

   <VirtualHost *:80>
       ServerName dev.example.org
       DocumentRoot /var/www/html/myproject/public # 确保DocumentRoot指向public目录
   
       <Directory /var/www/html/myproject/public>
           Options Indexes FollowSymLinks
           AllowOverride All         # 确保此行存在且设置为 All
           Require all granted
       </Directory>
   
       ErrorLog ${APACHE_LOG_DIR}/dev_error.log
       CustomLog ${APACHE_LOG_DIR}/dev_access.log combined
   </VirtualHost>

   登录后复制

   注意事项：

   

   降重鸟

   要想效果好，就用降重鸟。AI改写智能降低AIGC率和重复率。

   113

   查看详情
   • DocumentRoot应指向你的项目中的public目录，这是前端控制器index.php所在的目录。
   • <Directory>指令的路径也应与DocumentRoot一致，或包含DocumentRoot所在的路径。
   • 如果你的项目在子目录中，例如http://dev.example.org/myproject，则DocumentRoot可能指向/var/www/html，而<Directory>指令应指向/var/www/html/myproject或/var/www/html/myproject/public，具体取决于你的.htaccess规则和应用设计。

3. 保存并重启Apache： 修改完成后，保存文件并重启Apache服务，使更改生效。

   sudo systemctl restart apache2
   # 或者
   sudo service apache2 restart

   登录后复制

2.2 启用 URL 重写模块：mod_rewrite

.htaccess文件中的RewriteRule指令由Apache的mod_rewrite模块处理。如果此模块未启用，则所有重写规则都将无效。

操作步骤：

1. 检查mod_rewrite状态： 可以使用apachectl -M命令列出所有已启用的Apache模块。

   apachectl -M | sort | grep rewrite_module

   登录后复制

   如果输出中包含rewrite_module (shared)，则表示模块已启用。如果没有，则需要手动启用。

2. 启用mod_rewrite模块： 在Debian/Ubuntu系统上，可以使用a2enmod工具启用Apache模块。

   sudo a2enmod rewrite

   登录后复制

   该命令会在/etc/apache2/mods-enabled/目录下创建一个指向/etc/apache2/mods-available/rewrite.load的符号链接。

3. 重启Apache： 启用模块后，同样需要重启Apache服务以加载新模块。

   sudo systemctl restart apache2
   # 或者
   sudo service apache2 restart

   登录后复制

3. 项目 .htaccess 规则解析

提供的.htaccess规则是典型的PHP前端控制器模式的实现：

RewriteEngine On                   # 启用重写引擎
RewriteCond %{REQUEST_FILENAME} !-f # 如果请求的文件名不是一个实际存在的文件
RewriteRule (.*) public/index.php/$1 [L] # 则将所有请求重写到 public/index.php，并将原始请求路径作为参数传递

这条规则的目的是：

• 当请求的文件（如/image.png）实际存在时，直接提供该文件。
• 当请求的文件（如/users/1）不存在时，将其内部重写到public/index.php，并将/users/1作为index.php的路径信息（PATH_INFO）传递，由PHP应用进一步处理。
• [L]标志表示这是最后一条规则，停止进一步的重写。

4. 故障排除与验证

• 检查Apache错误日志： 如果在执行上述步骤后问题依然存在，请检查Apache的错误日志（通常在/var/log/apache2/error.log或虚拟主机配置中指定的路径）。日志中可能会有更详细的错误信息，帮助你定位问题。
• 验证DocumentRoot： 确保你的虚拟主机配置中的DocumentRoot指令正确指向了包含index.php的public目录。
• 权限问题： 确保Apache用户（通常是www-data）对项目目录及其文件拥有足够的读取权限。
• Plesk环境： 如果使用Plesk，某些配置可能需要通过Plesk面板进行，或Plesk会生成自己的Apache配置文件。在Plesk中，通常可以在“Web服务器设置”或“Apache & Nginx 设置”中找到AllowOverride的选项。

总结

当PHP项目在部署后遇到.htaccess URL重写失败并显示“File not found”错误时，最常见的原因是Apache服务器未正确配置以允许.htaccess文件生效或未启用URL重写模块。通过确保虚拟主机配置中的<Directory>块包含AllowOverride All指令，并启用mod_rewrite模块，然后重启Apache服务，通常可以解决此类问题。理解.htaccess规则的工作原理和Apache的配置机制，是成功部署此类PHP应用的关键。

以上就是解决PHP项目.htaccess URL重写部署失败：Apache配置指南的详细内容，更多请关注php中文网其它相关文章！