必须先执行a2enmod php8.1并禁用旧模块（如php7.4、php8.0），再验证apache2ctl -M | grep php输出唯一php8_module (shared)，否则后续配置无效；同时需在VirtualHost中配置FilesMatch和Directory权限，并确保hosts绑定、服务重启及phpinfo()测试文件正确部署。
确认 Apache 已加载 php8_module 而非旧版模块
没加载对模块，后面所有配置都白搭。Ubuntu/Debian 系统下，a2enmod php8.1 必须执行，且要 a2dismod php7.4 php8.0（如果存在）。Windows 或 macOS 手动编译环境则需检查 httpd.conf 中 LoadModule php_module 指向的路径是否对应 PHP 8.1 的 php8apache2_4.dll 或 libphp.so。
验证命令必须跑一次：apache2ctl -M | grep php（Linux/macOS）或 httpd -M | findstr php（Windows），输出里只能有 php8_module (shared)，不能混着 php7_module。
常见错误现象：
- 访问
.php文件直接下载源码 → 模块未加载或AddHandler缺失 - 500 错误且 error.log 提示 “Invalid command ‘php_value’” → 加载了旧版模块但用了 PHP 8.1 的 ini 指令语法
在 VirtualHost 中正确声明 PHP 处理器和入口路径
Apache 不会自动把 .php 当脚本执行，必须显式告诉它怎么处理。不是加个 AddType 就够——从 Apache 2.4.32 开始，AddHandler + SetHandler 组合更可靠。
立即学习“PHP免费学习笔记（深入）”；
在你的 VirtualHost 块内（如 /etc/apache2/sites-available/myapp.conf），必须包含：
<FilesMatch \.php$>
SetHandler application/x-httpd-php
</FilesMatch>
同时确保 DocumentRoot 指向真实存在的目录，且该目录下有 index.php；如果是 Laravel/ThinkPHP 类框架，DocumentRoot 必须是 public/ 子目录，不能是项目根目录。
别漏掉 <Directory> 权限块：
-
AllowOverride All（支持.htaccess重写） -
Require all granted（Apache 2.4+ 必须，旧版Order Allow,Deny已失效）
hosts 绑定 + vhosts 启用缺一不可
本地测试时，浏览器根本不会把请求发到你本机 Apache，除非系统 hosts 文件先做了映射。编辑 /etc/hosts（Linux/macOS）或 C:\Windows\System32\drivers\etc\hosts（Windows），加一行：
127.0.0.1 myapp.test
然后确认 Apache 主配置已启用虚拟主机支持：
- Ubuntu/Debian：
Include /etc/apache2/sites-enabled/*.conf必须在apache2.conf里启用 - macOS 自带 Apache：
Include /private/etc/apache2/extra/httpd-vhosts.conf那行不能注释 - Windows XAMPP：
httpd.conf中Include conf/extra/httpd-vhosts.conf必须取消注释
改完 hosts 和配置后不重启 Apache，等于没改。命令统一用：sudo systemctl restart apache2（Linux）或 sudo apachectl restart（macOS）或 httpd -k restart（Windows）。
测试文件必须放对位置且内容不含语法错误
最简验证方式是建一个 test.php 放在 DocumentRoot 目录下，内容仅一行：<?php phpinfo(); ?>。注意：
- 不要用短标签
<? ... ?>，PHP 8.1 默认禁用short_open_tag - 文件编码保存为 UTF-8 无 BOM，否则可能触发空白输出导致 headers already sent
- 路径权限要对：Apache 进程用户（如
www-data）必须有读取权限，ls -l看一眼
访问 http://myapp.test/test.php，看到 PHP 信息页才算真正走通。如果只显示白屏或 500，立刻查 /var/log/apache2/error.log（Linux）或 /usr/local/var/log/httpd/error_log（macOS），里面第一行报错往往就是根因。
容易被忽略的是：PHP 8.1 的 php.ini 里 display_errors = On 和 error_reporting = E_ALL 必须打开，否则语法错误静默失败，连日志都不记。
