services.yaml必须以services:开头并正确缩进，核心是显式声明class、精准匹配arguments/calls参数类型与顺序，引用用@和%，imports需置于顶部且路径相对config/目录。
services.yaml 不是“怎么写都行”的配置文件，它直接决定容器里有哪些服务、怎么构造、是否公开、能否自动注入。配错轻则服务拿不到，重则整个容器编译失败或行为诡异。
services.yaml 的核心结构必须是 services: 块
YAML 文件顶层必须以 services: 开头，后面缩进定义具体服务。任何其他写法（比如漏掉冒号、缩进不一致、混用 tab 和空格）都会导致 Symfony\Component\DependencyInjection\Exception\RuntimeException 或解析失败。
- 正确写法：
services:后换行，所有服务定义缩进 2 个空格（推荐） - 错误高发点：用 tab 缩进；
services写成service；在services:行末加多余字符（如:后跟空格再换行） - 常见报错：
The file ".../config/services.yaml" does not contain valid YAML，基本就是语法或缩进问题
注册类服务时 class: 必须显式声明
即使类在 App\ 命名空间下且已启用自动加载，也不建议依赖自动绑定（App\: resource: '../src/*'）来注册关键服务——它不控制构造参数、作用域和可见性，容易被覆盖或忽略。
- 显式注册更安全：
App\Service\EmailSender:→class: App\Service\EmailSender - 若省略
class:，Symfony 会尝试用服务 ID 当类名，比如App\Service\EmailSender:等价于class: App\Service\EmailSender，但仅当 ID 是合法 FQCN 且无歧义时才成立；一旦 ID 带别名（如email.sender.v2），就必须写class: - 第三方类（如
GuzzleHttp\Client）必须写class:，否则容器无法识别目标类
arguments 和 calls 要匹配构造函数与方法签名
arguments: 传给构造函数，calls: 调用 setter 方法，顺序和类型必须严格对应。PHP 8+ 的命名参数（name: value）在 YAML 中不生效，只能靠位置。
- 构造函数有三个参数：
__construct(LoggerInterface $logger, string $host, int $timeout)，那么arguments:必须按序写：['@logger', '%app.api_host%', '%app.timeout%'] - 引用其他服务用
@服务ID，引用参数用%参数名%，硬编码值直接写（字符串加引号更安全） -
calls:中的方法必须是 public，且参数数量不能少于定义的项数；多传会报错，少传可能静默失败但逻辑异常
imports 拆分配置时路径和顺序很关键
把大文件拆成 config/services/database.yaml、config/services/api_clients.yaml 是可行的，但 imports 不是“包含”，而是顺序合并——后导入的同名服务会完全覆盖前面的。
-
imports:必须写在services.yaml最顶部（在parameters:之后、services:之前） - 路径是相对于
config/目录的，resource: 'services/database.yaml'才对；写成../services/database.yaml会报File not found - 生产环境改了任意一个子文件，必须运行
bin/console cache:clear --env=prod，否则旧缓存仍生效
public: false。YAML 看似简单，但 service ID 冲突、参数未解析、作用域误配这些问题，往往要等到第一次调用时才暴露。 
