--prefer-source 不强制所有包走 Git 克隆，仅对声明 source 字段或配置了 vcs 仓库的包生效；Packagist 上仅提供 dist 的包无效，需配合 repositories 配置、dev 分支约束及 clear-cache 才可靠触发源码克隆。

为什么 --prefer-source 有时根本没触发 Git 克隆

很多人执行 composer install --prefer-source 后发现包还是走 dist（zip 下载），根本没 clone。核心原因是：Composer 默认只对「开发依赖」或「启用了 source 仓库类型」的包才考虑源码模式；生产依赖（require）若来源是 Packagist，且该包在 dist 和 source 两者都提供时，Composer 优先选更快的 dist —— --prefer-source 并不强制覆盖所有包。

• 只有当包的 composer.json 中明确声明了 "source" 字段（含 type, url, reference），且该字段可用，--prefer-source 才会起作用
• 如果包在 Packagist 上只提供了 dist（比如私有包未配置 VCS 信息），加参数也无效
• composer update 比 install 更容易触发 source 模式，因为 update 会重新解析包元数据

如何确认某个包是否支持 --prefer-source

直接查它的 Packagist 页面或 composer show vendor/package 输出，重点看有没有 source 行：

composer show monolog/monolog
# 输出中包含：
source : [git] https://github.com/Seldaek/monolog.git 2c1584b6...

若看到类似 source : [git] ...，说明支持；若只有 dist : [zip] ...，那 --prefer-source 对它无效。

Digital IP Agent

将公开的创作者、博主、播客主持人、YouTuber 或 X/Twitter 账号人物转化为可部署的 OpenClaw 代理。当用户提供 YouTube 链接、X（推特）链接等时使用。

下载

• 私有 Git 仓库必须在 composer.json 的 repositories 中显式声明为 vcs 类型，否则 Composer 不识别其 source 能力
• 用 composer config -g repositories.packagist.org false 临时禁用 packagist.org，可迫使 Composer 尝试从你配的 VCS 拉源码（慎用，会影响其他包）

真正强制走 Git Clone 的实操组合

单靠 --prefer-source 不够稳，需配合配置和命令调整：

• 在项目根目录 composer.json 中添加仓库声明（以 GitHub 私有库为例）：

  {
    "repositories": [
      {
        "type": "vcs",
        "url": "https://github.com/your-org/your-package.git"
      }
    ]
  }

• 然后运行：composer require your-org/your-package:dev-main --prefer-source（注意用 dev-* 分支名，不是 ^1.0 这类稳定版本约束）
• 若已安装过，先删掉 vendor/your-org/your-package 和 composer.lock 中对应项，再执行 composer update your-org/your-package --prefer-source
• 验证是否成功：进 vendor/your-org/your-package 目录，运行 git remote -v —— 有输出即为 clone 成功；若目录里没有 .git，说明仍是 dist 解压

常见报错与绕过方式

遇到 Failed to download ...: Failed to execute git clone，通常不是参数问题，而是环境或权限卡点：

• Git 未安装或不在 $PATH：运行 git --version 确认；Windows 用户注意 Git Bash 和 CMD 的路径差异
• SSH URL（git@github.com:...）但没配 SSH key：改用 HTTPS URL，或运行 ssh-add ~/.ssh/id_rsa
• 公司网络拦截 Git 端口：设置 git config --global url."https://".insteadOf git://，并确保 Composer 使用 HTTPS 协议拉取
• GitHub token 权限不足（尤其私有库）：在 auth.json 中配 github-oauth 或用 composer config github-oauth.github.com <token></token>

最易被忽略的一点：Composer 缓存会记住上次安装方式。哪怕改了 repositories 和参数，旧缓存仍可能复用 dist 包。执行前先运行 composer clear-cache。