PHP的include_path必须显式设置，否则include/require仅在脚本所在目录和当前工作目录查找；推荐php.ini全局配置（最稳定），或运行时用set_include_path()动态追加（需get_include_path()拼接），Apache中php_value仅限mod_php且限制多。
PHP 的 include_path 必须显式设置，否则 include 和 require 只会在脚本所在目录和当前工作目录找文件，没法自动定位公共库。
php.ini 中全局设置 include_path（最稳定）
这是生产环境首选方式，一次配置、全站生效，且不受 PHP 运行模式（FPM / mod_php）限制。
- 用
phpinfo()或命令行php --ini确认你正在使用的php.ini路径（注意：CLI 和 Web SAPI 的配置文件可能不同） - 找到
include_path行，取消注释并写成符合系统分隔符的格式：
Linux/macOS：include_path = ".:/var/www/lib:/usr/share/php"
Windows：include_path = ".;C:\inetpub\wwwroot\lib;C:\php\pear" - 多个路径必须用
PATH_SEPARATOR对应的字符（:或;），不能混用 - 开头的
.表示“当前工作目录”，保留它可兼容未设路径的老代码；但若明确不想 fallback 到当前目录，可去掉 - 改完必须重启 Apache（或 PHP-FPM 服务），仅 reload 不生效
运行时用 set_include_path() 动态追加（开发/多租户场景）
适合无法修改 php.ini 的共享主机，或需要按请求差异化加载路径（比如多站点共用一份代码但库路径不同）。
- 必须在任何
include/require之前调用，否则已触发的查找不会重新走新路径 - 推荐用
get_include_path()拼接，避免覆盖默认值：set_include_path(get_include_path() . PATH_SEPARATOR . '/my/custom/lib'); -
PATH_SEPARATOR是跨平台关键——硬写:或;在换系统时会直接失效 - 该设置仅对当前请求生命周期有效，下个请求会重置为 php.ini 的初始值
- 注意：如果已在 php.ini 中禁用了
ini_set（如disable_functions = ini_set），此方法会静默失败
Apache 配置中用 php_value 设置（仅限 mod_php，易踩坑）
这个方式看似方便，但实际限制极多，不建议新项目使用。
立即学习“PHP免费学习笔记（深入）”；
- 只在 Apache + mod_php（即
libphp.so）模式下有效；PHP-FPM（通过proxy_fcgi）完全无视php_value - 需确保
AllowOverride Options或AllowOverride All开启，否则.htaccess中的php_value被忽略 - 虚拟主机配置中写法：
php_value include_path ".:/srv/site/lib"，路径分隔符仍须匹配系统 - 若 Apache 配置了
php_admin_flag allow_override Off，该指令会被强制拒绝 - 错误不报具体提示，常表现为路径没生效却查不出原因——优先检查 PHP SAPI 模式
验证是否生效及常见失效原因
别只信配置文件，一定要用代码验证。最容易被忽略的是路径查找顺序和缓存机制。
- 新建
test.php，内容为：<?php echo get_include_path(); ?>，访问后看输出是否含你设的路径 - 真正测试包含逻辑：
require 'SomeClass.php';，把SomeClass.php放进你设的路径里，而非脚本同目录 - 注意：如果
require参数带路径（如require './lib/SomeClass.php'），include_path完全不参与查找 - PHP 会对
include结果做 stat 缓存，删掉文件后可能短暂报错；调试时可在include前加clearstatcache(true) - Linux 下路径大小写敏感，Windows 不敏感——同一套配置在不同系统上可能表现不一致
最麻烦的不是设不对，而是设对了但没生效：先确认 PHP SAPI 模式，再核对 php.ini 路径，最后用 get_include_path() 实锤。路径拼接漏掉 PATH_SEPARATOR、重启服务遗漏、或误以为相对路径也走 include_path，这三类问题占实际故障的八成以上。
