绝大多数PHP文件操作函数不强制绝对路径，但CLI与Web双环境或多入口时必须用绝对路径；推荐以__DIR__为基准拼接，并在注释中用箭头标明真实解析路径。
PHP文件操作函数里哪些参数必须写绝对路径
绝大多数 PHP 文件操作函数（如 fopen、file_get_contents、copy、unlink）接受相对路径，但「相对」是相对于当前工作目录（getcwd()），不是相对于当前脚本位置。这导致很多人在 include 一个工具类后，文件操作突然找不到目标——因为 getcwd() 可能是 Web 服务器启动目录（如 /var/www），而不是你的 /var/www/project/lib/。
真正需要强制用绝对路径的场景只有两个：当脚本被 CLI 和 Web 两种方式调用时，或当项目存在多入口且工作目录不统一时（比如 Laravel 的 public/index.php 和 artisan 命令行入口）。
-
__DIR__是最安全的起点，它永远指向当前文件所在目录，不受chdir()或运行方式影响 - 拼接路径优先用
dirname(__DIR__) . '/data/config.json'，而不是../data/config.json'—— 后者在 symlink 环境下可能失效 - 避免用
$_SERVER['DOCUMENT_ROOT']拼路径，它只在 Web SAPI 下存在，CLI 下会 Notice
file_get_contents() 注释里怎么标清楚路径来源
直接写 file_get_contents('config.json') 是危险注释。读者无法判断这个 config.json 是从哪找的：当前目录？项目根目录？还是某个固定配置目录？你应该在注释里明确路径解析逻辑。
推荐写法是在函数调用上方加一行注释，用 // → /var/www/app/config/config.json 这种箭头格式标明实际解析结果，而不是描述意图。这样下次调试时一眼就能验证是否路径错了。
立即学习“PHP免费学习笔记（深入）”；
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
/** * 读取数据库配置 * → /var/www/app/config/db.php */ $config = file_get_contents(__DIR__ . '/../config/db.php');
- 箭头右侧必须是真实、可复现的绝对路径（可用
echo __DIR__ . '/../config/db.php';验证） - 不要写
// 路径：项目根目录下的 config/这种模糊描述 - 如果路径含变量（如
$env），注释里也得带值：→ /var/www/app/config/db.prod.php
fopen() 的 mode 参数和路径注释要联动说明
fopen() 的 mode 决定文件是否存在、是否创建、是否截断，这些行为和路径是否已存在强相关。只注释路径却不提 mode，等于没注释。
例如 fopen($logPath, 'a') 和 fopen($logPath, 'w') 对同一个路径会产生完全不同的副作用——前者追加，后者清空重写。如果 $logPath 指向的是共享日志文件，一个错写的 'w' 就会让其他进程日志丢失。
- 注释里必须包含 mode 含义，例如：
// 'a+'：追加写，文件不存在则创建 - 如果路径是动态生成的（如含日期），注释要体现该路径是否预期存在：
// /var/log/app/202405.log（每日新建，无需预创建） - 避免用
'c'或'x'这类冷门 mode，除非你真需要原子性创建，否则增加维护成本
用 realpath() 做路径校验时注释要留痕
有人会在打开文件前加 realpath($path) 来做合法性检查，但如果不注释清楚「为什么必须 realpath」，后来人很容易删掉它——尤其当测试环境路径简单时，realpath() 看起来像多余开销。
真实原因通常是：防止路径穿越（../../../etc/passwd）、解决 symlink 循环、或确保缓存键唯一（比如把 /var/www/app/storage/logs/ 和它的 symlink 路径归一化）。这些都得白纸黑字写进注释。
// realpath() 必须保留：防止 $filename 来自用户输入时触发路径遍历
// 同时确保所有软链接路径归一化，避免同一文件被多个路径缓存两次
$path = realpath($userProvidedPath);
if ($path === false) {
throw new InvalidArgumentException("Invalid path: $userProvidedPath");
}路径操作从来不是“写对就行”，而是“谁都能看懂为什么这么写”。最容易被忽略的，是那个没写进注释的隐含假设——比如“这个路径一定在 /tmp 下”或“open_basedir 已放开”。一旦假设失效，问题就藏得特别深。
