本文详解 Symfony Flex 私有 Recipe 的正确实现方式：私有 recipe 不支持 copy-from-recipe 目录映射，必须将配置文件内容内联至 JSON 的 files 字段，否则配置不会被安装到项目中。
本文详解 symfony flex 私有 recipe 的正确实现方式：私有 recipe 不支持 `copy-from-recipe` 目录映射，必须将配置文件内容内联至 json 的 `files` 字段，否则配置不会被安装到项目中。
在使用 Symfony Flex 为私有 Bundle 构建定制化安装体验时，一个常见误区是——误将公开 recipe 的目录结构逻辑直接套用于私有 recipe。根据 Symfony 官方机制，私有 recipe（即通过 SYMFONY_ENDPOINT 指向自托管 JSON 清单）与官方仓库 recipe 的行为存在关键差异：私有 recipe 不会读取 Git 仓库中额外的文件目录（如 config/），而是完全依赖 JSON 内联定义的 files 字段来注入文件内容。
这意味着，即使你在私有 recipe 仓库中创建了 config/edumedia_gar_api.yaml 文件，并在 manifest.copy-from-recipe 中声明 "config/": "%CONFIG_DIR%"，Flex 在安装时也会静默忽略该路径——因为私有 recipe 解析器不执行文件系统遍历，仅解析 JSON 中显式声明的 files。
✅ 正确做法：将配置文件内容以数组形式内联至 files 对象中。例如，你的 gar-api-bundle-recipe 应改为如下结构：
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
{
"manifests": {
"edumedia/gar-api-bundle": {
"manifest": {
"bundles": {
"eduMedia\GarApiBundle\eduMediaGarApiBundle": ["all"]
},
"env": {
"GAR_DISTRIBUTOR_ID": "000000000_0000000000000000",
"GAR_SSL_CERT": "/path/to/cert.pem",
"GAR_SSL_KEY": "/path/to/cert.key"
}
},
"files": {
"config/packages/edumedia_gar_api.yaml": {
"contents": [
"edumedia_gar_api:",
" distributor_id: '%env(GAR_DISTRIBUTOR_ID)%'",
" ssl_cert: '%env(GAR_SSL_CERT)%'",
" ssl_key: '%env(GAR_SSL_KEY)%'",
" remote_env: 'preprod'",
" cache_directory: '%kernel.cache_dir%/gar-cache'"
],
"executable": false
}
},
"ref": "ad610a54abdf2f5563841a4ce4b3c3cb29a7d0ff"
}
}
}
⚠️ 注意事项：
- files 键下的路径（如 "config/packages/edumedia_gar_api.yaml"）是目标路径，基于项目根目录解析，需符合 Symfony 标准目录约定；
- contents 必须为字符串数组，每行一个元素，换行符由 Flex 自动处理；YAML 缩进需手动维护，否则会导致解析失败；
- executable 字段仅对脚本类文件有意义，配置文件设为 false 即可；
- copy-from-recipe 字段在私有 recipe 中完全无效，应彻底移除，避免误导；
- 手动编写长 YAML 内容易出错，推荐开发阶段先按标准 public recipe 结构组织文件（含 recipes/edumedia/gar-api-bundle/1.0/config/packages/...），再使用 Symfony 官方工具 symfony/flex 的 dump-manifest 命令自动生成合规 JSON（详见 Stack Overflow 实践指南）。
总结：私有 recipe 的本质是「声明式清单」而非「文件分发包」。坚持将所有需注入的文件内容内联至 files，并确保 ref 指向包含该 JSON 的确切 commit，即可让 composer require edumedia/gar-api-bundle 稳定完成 Bundle 注册、环境变量注入与配置文件落地——真正实现开箱即用的私有生态集成。
