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

在开发 PHP 项目时，我们通常会依赖发布在 Packagist 上的第三方库。Composer 让安装与管理这些依赖变得非常轻松。

但如果你需要在本地修改并调试某个依赖，而不是每次都发布新版本或推送到 GitHub 呢？

例如：你的项目依赖一个库，你希望对库做的改动能立刻在主项目里生效，以便快速验证。Composer 的 repositories 选项就能做到这一点：你可以用本地目录覆盖 Packagist 上的同名依赖。

这篇文章会通过一个实际场景讲清楚：为什么这种工作流有用、如何配置，以及它能解决哪些常见问题。
原文链接 PHP 开发者指南 如何在 Composer 中使用本地包

场景

你正在开发一个 PHP 项目，它的 composer.json 依赖如下：

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

这里项目依赖了包 storyblok/php-management-api-client。通常 Composer 会从 Packagist 下载它。

但 repositories 中配置了一个 "type": "path" 的仓库后，Composer 会理解为：

不要从 Packagist 下载这个包，改用本机 ../php-management-api-client 目录中的那份拷贝。

这意味着你可以把这个库克隆到主项目旁边，在库里修改代码，然后在运行主项目时立刻看到这些改动生效。

为什么要使用本地包？

下面是一些非常常见、也非常实用的场景，这种工作流在这些情况下尤其好用。

1. 跨两个仓库同时开发功能或修复

你在主项目里开发一个新功能，但它需要依赖库也做相应改动。

与其等待依赖库合并、发布新版本，不如两个仓库并排开发。使用本地 path 仓库后，库的代码改动会立刻反映到主项目中。

2. 调试依赖库的行为

有时依赖库的行为不符合预期。你可能需要加日志、检查内部状态、或单步调试库代码来定位问题。

使用本地副本会让这种"深度调试"变得容易很多。

3. 给开源包贡献代码

如果你要给某个开源库提 PR，通常会希望先在真实项目里验证改动。

用本地 path 仓库可以避免为了测试而创建临时提交，也不必为了跑通流程专门用 fork。

4. 离线或受限网络环境下开发

这更像是一种变通方案：某些企业网络环境可能无法访问 GitHub 或 Packagist。

本地 path 包可以让你在开发期完全离线使用依赖。

5. 处理未发布版本或实验性 API

当你在尝试内部 API 或验证破坏性改动时，你可能还不想发布任何东西。

本地仓库给你一个更安全、可控的实验空间。

6. 快速迭代，不必频繁 bump 版本

快速迭代时，不停地修改语义化版本号或切分支会很麻烦。

本地 path 仓库可以让你先跳过版本管理，等准备好发布时再统一处理。

如何在 Composer 中使用本地包

你需要做的事情如下。

1. 在本地克隆依赖库

把依赖库克隆到主项目附近，例如：

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

注意：克隆出来的目录名不必与包名完全一致，只要路径与 repositories 的 url 配置匹配即可（见下一步）。

2. 修改 composer.json

新增一个指向该目录的 path 仓库：

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

3. 将依赖声明为开发版本

使用本地包时，Composer 需要知道你希望安装的是开发版本，而不是 Packagist 上的稳定版本。

实现方式有多种，但我认为最可靠的是：直接指定一个明确的 dev 分支版本号，通常就是 dev-main。

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

理解版本约束选项

Composer 支持多种版本约束。下面是使用 path 仓库时最相关的几种：

• dev-main：使用 main 分支上的开发版本。这是最可预测、也最推荐的方式，尤其当该库以 main 作为主要开发分支时。
• @dev ：允许 Composer 安装任意开发版本（例如 dev-main、dev-master 或其他 dev 分支）。它比 dev-main 更灵活，但不够明确。
• "*"：接受任意版本（稳定或 dev）。我以前用过，但不推荐，因为 Composer 可能会选到出乎意料的版本。

为了清晰与一致性，尤其当你使用本地克隆的库时，使用 dev-main 能确保 Composer 始终链接到你正在开发的那个分支（本例中为 main）。

4. 安装或更新

运行：

composer update storyblok/php-management-api-client

最佳实践

• 保持本地克隆仓库干净，避免提交临时调试代码。
• 完成开发后切回 Packagist 版本。
• 除非你明确希望这样做，否则不要把本地路径配置提交到仓库中。