应优先使用 composer require 安装已上架 packagist 的 sdk（如 alibabacloud/sdk）；若仅存 git 仓库，需配置 vcs repositories；仅当无 composer.json 时才最小化手动加载并用 autoload.files 声明。
Composer 引入第三方 SDK 不需要手动加载外部库——只要 SDK 提供了 composer.json 并发布到 Packagist 或支持的仓库，就该走标准 composer require 流程；手动拷贝 + require 或修改 autoload 是退化做法，容易导致版本混乱、依赖冲突、自动更新失效。
SDK 有 Packagist 包名（推荐：直接 require）
绝大多数主流 SDK（如 alibabacloud/sdk、tencentcloud/tencentcloud-sdk-php、aws/aws-sdk-php）都已注册到 Packagist。确认方式：打开 https://packagist.org/ 搜索 SDK 名称。
实操步骤：
- 运行
composer require vendor-name/package-name（例如：composer require alibabacloud/sdk） - Composer 自动写入
composer.json的require字段，并安装到vendor/ - 在代码中用
use导入类，无需额外require或include—— Composer 的自动加载机制已覆盖 - 如果 SDK 有初始化要求（如配置凭证），按其文档调用对应工厂类或客户端构造函数即可（例如：
AlibabaCloud\Client\AlibabaCloud::accessKeyClient(...)）
SDK 只有 GitHub/GitLab 仓库（无 Packagist，需指定 VCS 仓库）
有些团队内部 SDK 或未上架的开源 SDK，只有 Git 地址。此时不能靠 composer require 直接命中，但也不应手动复制文件。
正确做法是声明 repositories 并指定 type: vcs：
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/example-org/private-sdk"
}
],
"require": {
"example-org/private-sdk": "dev-main"
}
}
然后运行 composer require example-org/private-sdk:dev-main。注意：
-
example-org/private-sdk必须与该仓库composer.json中的name字段完全一致 - 分支名（如
dev-main）要和实际 Git 分支/Tag 匹配；若用 Tag，写成v1.2.0即可 - 不建议用
dev-master，因 Composer 8+ 默认禁用不稳定分支，需显式加"minimum-stability": "dev"（不推荐，改用具体分支或 Tag）
SDK 没有 composer.json（极少数遗留库，必须手动处理）
真遇到连 composer.json 都没有的 SDK（比如纯函数式 PHP 文件包），才考虑“手动加载”，但必须最小化侵入：
- 将 SDK 文件放入项目目录（如
thirdparty/alipay-sdk/），**不要放 vendor 下**（否则会被composer install清掉） - 在
composer.json的autoload中添加files数组，列出所有需全局加载的 .php 文件（注意：只适用于无命名空间、定义函数/常量的场景）：
"autoload": {
"files": [
"thirdparty/alipay-sdk/lib/core/function.php",
"thirdparty/alipay-sdk/lib/core/wap_submit.class.php"
]
}
之后运行 composer dump-autoload 生效。⚠️ 这种方式无法支持类自动加载（new AlipayWapSubmit() 会失败），除非 SDK 自己做了 __autoload 或你补全 PSR-0/4 映射 —— 通常得重写封装层，成本远高于推动 SDK 补 composer.json。
为什么别碰手动 require / include / set_include_path？
常见错误写法：require __DIR__.'/../thirdparty/sdk/xxx.php'; 或修改 set_include_path()：
- 破坏 Composer 自动加载统一性，IDE 无法跳转、静态分析失效
- 多个 SDK 间函数名冲突时无隔离（PHP 全局函数空间无命名空间）
-
composer update后路径变动或文件重命名，直接报failed to open stream - 无法被
composer show、composer outdated管理，安全漏洞和版本升级全靠人工盯
真正难的不是“怎么加进来”，而是判断 SDK 是否具备 Composer 友好结构；如果它连 composer.json 都不愿提供，大概率后续维护成本会持续反噬开发效率。
