Composer 可直接从本地文件系统加载包，但需满足：本地包含合法 composer.json（含唯一 name、version 或分支别名、autoload）；主项目 composer.json 用 path 类型 repositories 声明绝对路径；更新需 composer update；注意符号链接、缓存、命名冲突等问题。
Composer 可以直接从本地文件系统加载包，无需发布到 Packagist 或私有仓库，但必须满足几个关键条件，否则会报 Could not find package 或 no matching package found 错误。
本地包必须有合法的 composer.json
Composer 不识别任意目录，它只认符合规范的包定义。你的本地包根目录下必须存在 composer.json，且至少包含：
-
"name"（格式为vendor/name，不能重复或非法字符） -
"version"（如"1.0.0"）或使用"dev-main"等分支别名 -
"autoload"（否则无法自动加载类）
示例 composer.json（放在 /path/to/my-package/ 下）：
{
"name": "acme/utils",
"version": "1.0.0",
"autoload": {
"psr-4": {
"Acme\\Utils\\": "src/"
}
}
}
项目 composer.json 中用 repositories 声明本地路径
不能直接在 require 里写路径。必须先在主项目的 composer.json 里添加 repositories 配置，类型设为 path：
{
"repositories": [
{
"type": "path",
"url": "/path/to/my-package"
}
],
"require": {
"acme/utils": "*"
}
}
注意：url 必须是绝对路径（Linux/macOS）或带盘符的绝对路径（Windows，如 C:/projects/my-package）；相对路径不支持。
- 如果包目录里有多个
composer.json（比如含dev-develop和1.0.0），"*"会默认选最新稳定版；加"@dev"可强制走开发分支 - 修改本地包后，需运行
composer update acme/utils（不是install）才能同步变更
常见错误：符号链接、权限与缓存
即使配置全对，仍可能失败，原因多为：
- 目标路径被 symlinks 指向，而 Composer 默认禁用 symlink（尤其 Windows + WSL 组合）——加
"options": { "symlink": true }到 repository 配置中 - 路径含空格或中文，在某些 shell 下会被截断——改用英文路径，或用引号包裹（但 JSON 不支持引号转义，所以优先避免）
- Composer 缓存了旧的包元数据——执行
composer clear-cache后重试 - 本地包的
name与已 require 的其他包冲突（比如两个包都叫foo/bar）——检查composer show输出确认唯一性
最易忽略的一点：本地路径包不会自动触发 post-install-cmd 或 post-update-cmd 脚本，除非你在主项目中显式定义并调用它们。调试时建议先用 composer install -vvv 查看实际解析的包来源路径。
