如何在 Apache + PHP-FPM 环境中正确启用自定义 404 页面-php教程-PHP中文网

如何在 Apache + PHP-FPM 环境中正确启用自定义 404 页面

在 Apache 与 PHP-FPM 协同部署时，若 .htaccess 中的 ErrorDocument 404 失效，仅显示“File not found”，根本原因常是 PHP-FPM 的 SetHandler 无条件拦截所有匹配扩展名的请求（包括不存在的 PHP 文件），导致 404 响应被提前终止。解决方案是在 FilesMatch 中添加文件存在性校验。

在 apache 与 php-fpm 协同部署时，若 `.htaccess` 中的 `errordocument 404` 失效，仅显示“file not found”，根本原因常是 php-fpm 的 `sethandler` 无条件拦截所有匹配扩展名的请求（包括不存在的 php 文件），导致 404 响应被提前终止。解决方案是在 `filesmatch` 中添加文件存在性校验。

在传统 Apache + mod_php 环境中，ErrorDocument 404 能正常工作，因为请求路径未命中真实文件时，Apache 会自然触发 404 并跳转至自定义页面。但在 Apache + PHP-FPM 架构下，常见配置（如 /etc/httpd/conf.d/php.conf）通常使用如下无条件代理规则：

<filesmatch>
    SetHandler "proxy:unix:/run/php-fpm/www.sock|fcgi://localhost"
</filesmatch>

该配置的问题在于：只要请求 URL 以 .php 或 .phar 结尾，无论对应文件是否存在，Apache 都会尝试将其转发给 PHP-FPM 处理。而当文件实际不存在时，PHP-FPM 无法执行，直接返回 Status: 404 Not Found 和明文 "File not found." —— 此响应绕过了 Apache 的 ErrorDocument 机制，导致自定义 404 页面（如 /404）完全不生效。

✅ 正确做法是：仅对真实存在的 PHP 文件启用代理处理，将 SetHandler 包裹在条件块中。修改 /etc/httpd/conf.d/php.conf 对应段落如下：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

<filesmatch><if>
        SetHandler "proxy:unix:/run/php-fpm/www.sock|fcgi://localhost"
    </if></filesmatch>

⚠️ 注意事项：

修改后必须重启 Apache（sudo systemctl restart httpd），而非重载（reload），因部分版本需完整重启才能加载更新后的条件判断逻辑；
确保 mod_rewrite 已启用（用于 .htaccess 中的 RewriteEngine），且主配置中允许 .htaccess 覆盖（AllowOverride All 或至少 AllowOverride FileInfo）；
ErrorDocument 404 推荐使用相对路径（如 /404）而非绝对 URL（如 https://nobleme.com/404），避免额外重定向和 HTTPS 证书依赖；
若站点启用了 ProxyErrorOverride On，请务必移除——它会强制覆盖后端（PHP-FPM）返回的所有错误响应，干扰 Apache 原生错误处理流程，属于反模式。

最终验证：访问一个不存在的 .php 路径（如 /nonexistent.php），应看到你的自定义 404 页面；同时，真实存在的 PHP 脚本仍能正常执行。这一改动既保障了 PHP-FPM 的按需代理，又恢复了 Apache 完整的错误响应控制能力。