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，还有一些细节需要注意：
-
明确目标： 你是要让你的 项目 依赖的 某个包 里面的子模块可用？还是你的 项目本身 作为一个包，它的子模块需要被其他项目使用？
-
情况一（最常见）：项目依赖的包有子模块。 此时，你需要在 你的项目 的
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安装之前或之后，通过自定义脚本来拉取这些子模块，并编译出最终的资产。然后，你的主项目只需要依赖这些最终的资产，而不是子模块本身。这在一些前端资源管理上比较常见。
直接包含（不推荐）： 对于极小且不经常变动的代码片段，你也可以选择直接将子模块的代码复制到你的主项目中。但这会带来代码重复和更新困难的问题，通常不被推荐，除非有非常特殊的理由。
选择哪种方案取决于你的具体需求、团队结构和项目的长期维护策略。但总的来说，尽量避免在Composer依赖中直接使用子模块，通过将其拆分为独立的Composer包或采用Monorepo结构，通常能带来更清晰、更易于管理的依赖关系。
