如何在 Composer 中使用本地包：PHP 开发者指南

Source: Dev.to

在 PHP 项目中工作时，通常会依赖发布在 Packagist 上的外部库。Composer 让安装和管理这些依赖变得轻而易举。但如果需要在本地（而不是 Packagist）使用某个依赖该怎么办？

为什么使用本地路径仓库？

• 快速迭代 – 在库中立即测试修改，无需发布新版本或推送到 GitHub。
• 深入调试 – 添加日志、检查内部状态，或逐步执行库代码。
• Pull‑request 测试 – 在真实项目中验证更改后再提交 PR。
• 离线开发 – 在阻止访问 GitHub 或 Packagist 的环境中也能工作。
• 实验性工作 – 尝试破坏性更改或内部 API 而无需发布任何内容。
• 版本管理便利 – 在快速迭代时跳过语义版本号的提升。

典型场景

你的项目的 composer.json 可能如下所示：

{
  "require": {
    "storyblok/php-management-api-client": "@dev",
    "vlucas/phpdotenv": "^5.6"
  },
  "repositories": [
    {
      "type": "path",
      "url": "../php-management-api-client"
    }
  ]
}

repositories 条目中的 "type": "path" 告诉 Composer 使用位于 ../php-management-api-client 的副本，而不是从 Packagist 下载该包。这使你可以把库克隆到项目旁边，修改后立即看到效果。

设置本地包

1. 将库放在项目附近

   ~/Projects/my-project
   ~/Projects/php-management-api-client   ← 克隆的库

   文件夹名称 不必 与包名匹配；只要路径与 composer.json 中定义的 URL 相符即可。

2. 添加带有 symlink 选项的路径仓库

   // composer.json (excerpt)
   "repositories": [
     {
       "type": "path",
       "url": "../php-management-api-client",
       "options": {
         "symlink": true
       }
     }
   ]

   使用 "symlink": true 会创建符号链接，这样库中的更改会立即生效，无需重新安装。

3. 要求使用开发版本

   Composer 必须知道使用的是开发分支而非稳定发布。最可靠的方式是指定具体的 dev 分支，例如 dev-main：

   "require": {
     "storyblok/php-management-api-client": "dev-main"
   }

可能遇到的版本约束

更新本地依赖

运行以下命令来安装或更新本地包：

composer update storyblok/php-management-api-client

最佳实践

• 保持本地克隆的整洁 – 避免提交临时调试代码。
• 开发完成后切回 Packagist 版本。
• 除非有意为团队开发工作流提供，否则不要将本地路径配置提交到代码仓库。

遵循这些步骤，你就可以在主项目旁边无缝地开发依赖库，加快开发速度并简化调试过程。