需在 composer.json 的 autoload 字段显式配置：1. psr-4 用于有命名空间的规范代码；2. classmap 用于无命名空间的旧类库；3. files 用于全局函数/常量脚本；改后须运行 composer dump-autoload。
composer.json 里怎么配 autoload 自定义路径
Composer 默认只扫描 src/ 和 PSR-4 声明的命名空间，想加载项目根目录下的 helpers/ 或 legacy/ 这类非标准目录，必须显式告诉它。核心是改 autoload 字段，不是靠文件摆放位置。
常用方式有三种，按优先级和适用场景列出来：
-
psr-4：适合有命名空间、结构规范的代码，比如
"App\\Helper\\": "helpers/"—— 注意末尾斜杠不能少，且命名空间末尾必须带双反斜杠 -
classmap：适合无命名空间的旧代码或函数库，比如
"classmap": ["legacy/", "functions.php"]—— Composer 会静态扫描这些路径下所有.php文件并建立类名到文件的映射 -
files：适合全局函数、常量定义这类必须每次加载的脚本，比如
"files": ["helpers/global_functions.php"]—— 这些文件会在每次autoload.php被引入时无条件执行
改完记得运行 composer dump-autoload，否则新配置不生效。如果加了 files，还要注意避免重复包含（比如被其他地方 require_once 两次）。
加载没有 composer.json 的第三方包（比如 Git 子模块或私有库）
这类包没发布到 Packagist，也没有自己的 composer.json，但你想用 require 引入又不想手动 include，就得靠 repositories + package 手动注册。
在你项目的 composer.json 里加一段：
"repositories": [
{
"type": "package",
"package": {
"name": "myorg/legacy-tool",
"version": "1.0.0",
"autoload": {
"files": ["src/init.php"]
},
"dist": {
"url": "https://example.com/legacy-tool-1.0.0.zip",
"type": "zip"
}
}
}
]
然后运行 composer require myorg/legacy-tool:1.0.0。关键点：
-
type: "package"表示这是手动定义的包，不是从 Packagist 拉的 -
dist.url必须指向可下载的归档（zip/tar），不能是 Git 地址（那得用vcs类型） -
autoload写法和主项目一样，files最常用，因为老包基本没命名空间
为什么 vendor/autoload.php 不自动加载我的自定义 files？
常见现象：加了 "files": ["helpers.php"] 到 autoload，也跑了 dump-autoload，但函数还是报 Call to undefined function。
原因通常就两个：
- 没真正引入
vendor/autoload.php—— 检查你的入口文件（如index.php）是否写了require __DIR__ . '/vendor/autoload.php'; -
helpers.php里用了namespace但没加use或全限定名，而files加载不走命名空间解析，纯靠文件包含顺序 —— 简单起见，files里的代码最好别写namespace
还有一个隐藏坑：composer install 时如果用了 --no-autoloader 或 --classmap-authoritative，可能跳过 files 加载逻辑，调试时先去掉这些 flag。
classmap 和 files 在性能与维护性上的实际差别
两者都能加载任意 PHP 文件，但行为完全不同：
-
classmap是一次性扫描生成映射表，运行时按类名查文件路径，适合类多、结构稳定的老系统；缺点是新增类后必须重跑dump-autoload，否则找不到 -
files是每次请求都require_once那些文件，适合工具函数、配置初始化；优点是改了立刻生效，缺点是哪怕只用其中一个函数，整个文件也得加载，可能拖慢启动速度
如果一个目录里既有类又有函数，别混着用 —— 要么全走 classmap（把函数封装成工具类），要么全走 files（把类也改成函数式调用）。混用容易导致类已加载但函数未加载，或者反过来。
最麻烦的是 autoload 配置嵌套太深：比如主项目用 psr-4，子包用 files，另一个又用 classmap，最后谁先加载、变量是否污染、常量是否重复定义，全得靠实测。这种时候建议统一收口到一个 bootstrap.php 手动管理，别全扔给 Composer。
