composer如何处理git依赖中的submodule

34次阅读

Composer不自动处理Git子模块，需在composer.json中配置source模式并添加post-install-cmd和post-update-cmd脚本，执行git submodule update –init –recursive以拉取子模块内容。

Composer在处理Git依赖中的子模块时，并不会自动地初始化或更新它们。这意味着当你通过Composer安装一个包含子模块的Git仓库作为依赖时，Composer只会克隆或下载主仓库的内容，而子模块指向的目录将是空的，或者只包含一个指向子模块commit的

.git

文件，实际的代码内容并不会随之而来。你需要额外的步骤来确保子模块的内容被正确拉取。

解决方案

要解决Composer不自动处理Git子模块的问题，核心思路是在Composer安装或更新完成后，手动执行Git子模块的初始化和更新操作。这通常通过在项目的

composer.json

文件中配置

scripts

来实现。

首先，确保你的项目（或者包含子模块的那个依赖包，如果它是你正在开发的）在Composer安装时使用的是

source

模式而不是

dist

模式。因为

dist

模式下载的是一个压缩包，不包含

.git

目录，也就无法执行子模块相关的Git命令。你可以在

composer.json

中设置：

{     "config": {         "preferred-install": {             "*": "dist",             "your/package-with-submodules": "source" // 针对特定包         }     } }

或者，如果你的整个项目都依赖于Git操作，可以全局设置为

source

：

{     "config": {         "preferred-install": "source"     } }

然后，在你的主项目（即

composer.json

所在的项目）的

scripts

部分添加一个

post-install-cmd

或

post-update-cmd

钩子，让它在Composer操作完成后执行

git submodule update --init --recursive

命令。

{     "scripts": {         "post-install-cmd": [             "@php -r "if (file_exists('vendor/your/package-with-submodules/.git')) { chdir('vendor/your/package-with-submodules'); passthru('git submodule update --init --recursive'); chdir('../../'); }""         ],         "post-update-cmd": [             "@php -r "if (file_exists('vendor/your/package-with-submodules/.git')) { chdir('vendor/your/package-with-submodules'); passthru('git submodule update --init --recursive'); chdir('../../'); }""         ]     } }

这里我们用了一个简单的PHP脚本来判断

vendor/your/package-with-submodules

目录下是否存在

.git

目录（这表示它是通过

source

方式安装的），如果存在，就进入该目录执行子模块更新命令。

chdir('../../')

是为了确保脚本执行完后回到项目根目录。

如果你的项目中存在多个依赖包都使用了子模块，或者你希望更通用地处理所有安装的Git依赖中的子模块，这个脚本可能会变得复杂。通常，更推荐的做法是避免在Composer依赖中直接使用子模块，或者将子模块本身发布为独立的Composer包。

为什么Composer默认不处理Git子模块？

这其实是一个关于职责边界的问题。Composer被设计为一个PHP包管理器，它的核心职责是解析依赖关系、下载包文件并将它们放置在正确的位置（通常是

vendor

目录）。它将Git视为一个内容源，而不是一个需要深度介入并管理其内部结构（如子模块）的工具。

当你执行

composer install

或

composer update

时，如果一个依赖包指定了Git仓库作为源，Composer会调用底层的Git命令来克隆或拉取这个仓库。但Git本身的

clone

操作并不会自动初始化和更新子模块。子模块在Git中更像是一个指向另一个仓库特定提交的指针，而不是直接包含其内容的目录。要获取子模块的内容，需要额外的

git submodule update --init --recursive

命令。

如果Composer要承担子模块的管理职责，它就必须：

识别所有依赖包中的子模块。
递归地处理这些子模块，可能还要处理子模块的子模块。
处理子模块可能存在的版本冲突或兼容性问题。
在
```
dist
```
模式下（下载压缩包）提供一种替代机制，因为此时
```
.git
```
信息已丢失。

这样做会显著增加Composer的复杂性，偏离其作为包管理器的核心定位。因此，它选择将更底层的Git操作细节留给用户或项目本身来处理，通过脚本钩子提供了一种扩展机制。从我的角度看，这是一种务实的权衡，虽然给开发者带来了一点点不便，但保持了Composer的专注和高效。

如何在Composer项目中确保子模块内容可用？

确保Composer项目中的子模块内容可用，关键在于理解Composer的生命周期钩子和Git子模块的工作方式。除了前面提到的

post-install-cmd

和

post-update-cmd

，还有一些细节需要注意：

Movie Gen

Movie Gen 是 Meta 公司最新推出的AI视频生成大模型

90

查看详情

明确目标： 你是要让你的项目依赖的 某个包 里面的子模块可用？还是你的 项目本身 作为一个包，它的子模块需要被其他项目使用？
- 情况一（最常见）：项目依赖的包有子模块。 此时，你需要在 你的项目 的
```
composer.json
```
  中添加脚本，去更新
```
vendor/your/package-with-submodules
```
  下的子模块。这是因为你的项目是最终的执行环境。
```
// project-root/composer.json {     "scripts": {         "post-install-cmd": [             "@php -r "if (file_exists('vendor/some-vendor/some-package/.git')) { chdir('vendor/some-vendor/some-package'); passthru('git submodule update --init --recursive'); chdir('../../'); }""         ]     } }
```
- 情况二：你的项目本身是一个包，它有子模块。 如果你的包（
```
my/awesome-package
```
  ）里面有子模块，并且你希望其他项目安装
```
my/awesome-package
```
  时，它的子模块也能被拉取，那么这个责任就不完全在 你的包 的
```
composer.json
```
  里。因为其他项目安装你的包时，它们会拉取你的包，但不会自动执行你的包里的
```
post-install-cmd
```
  。在这种情况下，你需要：
  - 在你的包的文档中明确指出，使用你的包的项目需要手动执行
```
git submodule update
```
    。
  - 或者，考虑将子模块拆分成独立的Composer包，这是更符合Composer哲学的方式。
  - 如果你的包只是供内部开发使用，你可以在你的包的
```
composer.json
```
    中添加脚本，供你在开发时使用，但这不会影响到其他依赖你的包的用户。
preferred-install: source

的重要性： 再次强调，如果Composer以
```
dist
```
模式（下载压缩包）安装依赖，那么
```
.git
```
目录将不存在，所有
```
git submodule
```
命令都将失败。因此，对于任何包含子模块的依赖，必须强制Composer以
```
source
```
模式安装。这可以通过全局设置，或者针对特定包设置。
CI/CD环境： 在持续集成/持续部署（CI/CD）流程中，你可能需要在
```
composer install
```
之后明确地执行子模块更新命令，以确保构建环境拥有完整的代码。即使你配置了
```
post-install-cmd
```
，在某些CI环境中，为了确保一切按预期运行，显式地执行这个命令也是一个好习惯。

这些步骤共同构成了一个相对健壮的策略，用以弥补Composer在子模块处理上的空白。

使用子模块作为Composer依赖的替代方案有哪些？

虽然通过脚本可以解决Composer中子模块的问题，但从长远来看，这通常被视为一种“修补”而不是最佳实践。子模块在某些场景下有其优势，但在Composer生态中，它引入了额外的管理复杂性。这里有一些替代方案，可以帮助你避免在Composer依赖中直接使用子模块：

将子模块提升为独立的Composer包： 这是最符合Composer哲学的方式。如果你的子模块是一个独立的、可重用的组件，那么就把它发布为一个独立的Composer包。这样，你的主项目可以直接通过
```
composer require
```
来依赖它，Composer会负责所有的依赖管理和版本控制，而无需关心Git子模块的细节。这是最推荐的做法，它能带来更好的模块化和可维护性。
Monorepo与

path

仓库： 如果子模块是你的大型项目中的一个内部组件，并且你希望它们都在同一个Git仓库中管理，那么可以考虑采用Monorepo（单一代码仓库）结构。在这种结构下，你可以将子模块的内容直接放在主仓库的一个子目录中，然后通过Composer的
```
path
```
仓库类型来引用它。
```
// composer.json {     "repositories": [         {             "type": "path",             "url": "./packages/my-internal-component" // 指向子模块原本的位置         }     ],     "require": {         "my-org/my-internal-component": "@dev" // 像普通包一样引用     } }
```
这种方式使得所有代码都在一个仓库中，简化了克隆和部署，同时Composer仍能以其熟悉的方式管理内部依赖。
使用构建工具或脚本预处理： 如果子模块仅仅是为了提供一些编译后的资产（如前端JS/CSS库），你可以在项目的构建流程中，在Composer安装之前或之后，通过自定义脚本来拉取这些子模块，并编译出最终的资产。然后，你的主项目只需要依赖这些最终的资产，而不是子模块本身。这在一些前端资源管理上比较常见。
直接包含（不推荐）： 对于极小且不经常变动的代码片段，你也可以选择直接将子模块的代码复制到你的主项目中。但这会带来代码重复和更新困难的问题，通常不被推荐，除非有非常特殊的理由。