PHP文件包含报错主因是路径解析错误或权限不足：include按include_path和__DIR__查找文件，而非当前工作目录；相对路径如../会忽略include_path；Linux需检查www-data等进程用户对文件及各级目录的r/x权限。
PHP 文件包含报错，绝大多数情况不是语法写错了，而是路径没对上、文件根本没被 PHP 找到，或者找到了但读不了。
include 路径解析不按你想象的方式工作
PHP 的 include 默认不看当前命令行在哪执行，也不看 Web 请求从哪个 URL 进来，它只认两件事：一是 include_path 配置的目录列表，二是调用 include 那行代码所在脚本的目录（即 __DIR__）。如果路径既不在 include_path 里，又不是相对于 __DIR__ 的有效路径，就会报 “failed to open stream”。
- 写
include 'config.php';时，PHP 先去include_path查，查不到再去找当前脚本所在目录下的config.php - 写
include '../lib/helper.php';，include_path直接被忽略，只在当前脚本目录的父目录下找 - 用
getcwd()打印当前工作目录，和__DIR__经常不一样——尤其在 CLI 下运行时，getcwd()是你敲命令的位置，__DIR__才是脚本真实位置
文件存在但权限或编码导致报错
Linux 下常见报错 “Permission denied”，不是路径错，是 PHP 进程用户（如 www-data 或 nginx）没有读取文件或中间目录的权限。Windows 不报权限错，但大小写不一致（比如写了 Config.php 却引用 config.php）在 Linux 上直接 404。
- 确认目标文件可读：
ls -l /path/to/file.php，检查权限位末三位是否含r - 确认路径中每一级目录都有
x权限（否则无法进入该目录） - 用
head -n1 file.php | hexdump -C检查是否有 BOM（输出含ef bb bf就得清除），BOM 会导致解析器第一行就读出错，报 “unexpected ‘}’” 这类误导性错误 - FTP 上传务必设为“二进制模式”，ASCII 模式会悄悄损坏换行符或插入控制字符
VS Code 里标红但运行正常？那是 Intelephense 没配对
编辑器报 “Unresolved include” 不代表 PHP 运行时报错，只是静态分析工具猜错了路径起点。Intelephense 默认只扫描工作区根目录，不会自动理解你用 __DIR__ . '/../config/db.php' 这种写法的真实意图。
立即学习“PHP免费学习笔记（深入）”；
- 必须手动配置
intelephense.environment.includePaths，填绝对路径或带${workspaceFolder}的相对路径 - 右键点击实际入口文件（如
public/index.php），选 “Intelephense: Set as entry point” -
php.ini里的include_path对 Intelephense 完全无效，别指望它自动同步 - 改完配置后要重启整个 VS Code 窗口，仅重载不够
ThinkPHP 或 Laravel 里突然报 “Filename cannot be empty”
这不是你写的 include 出了问题，是框架底层在拼路径时某个变量为空。典型场景：环境配置缺失（如 .env 里数据库前缀没填）、自动加载器找不到类、模板路径配置写成空字符串、或者异常处理器在兜底时传了个空路径给 include。
- 错误堆栈指向
think\exception\Handle.php第 184 行？别修它，往上翻，看哪一行调用了include并传入了空值 - 临时在入口文件开头加
var_dump($_ENV, $_SERVER['DOCUMENT_ROOT'], get_included_files());，快速定位缺失配置 - 检查所有
define()、env()、config()调用，确保返回值不是null或空字符串 - Docker 环境下特别注意：.env 文件是否挂载成功、是否被覆盖、是否用了错误的环境变量名
最麻烦的从来不是路径写错，而是路径“看起来对”，但因为符号链接、opcache 缓存旧路径、IDE 插件误判、或者部署时某一层目录权限漏设，导致问题只在特定环境复现。动手前先确认 __DIR__ 和实际文件物理位置是否一致，比瞎试十种写法更省时间。
