Yii框架连接MongoDB三大卡点：扩展与PHP/Yii2版本必须严格对齐；DSN必须带数据库名且认证参数完整；模型必须显式返回['\_id']作主键，否则查询为空、保存报错或静默失败。
Yii 框架连接 MongoDB 不是“配个 DSN 就能用”，核心卡点在三个地方：扩展版本与 PHP/Yii2 版本必须严格对齐、dsn 必须带数据库名且认证参数不能漏、模型主键必须显式返回 ['_id']。错一个，find() 返回空、save() 报 BadMethodCallException 或直接静默失败。
composer require yii2-mongodb 失败或提示包不存在
不是命令写错，也不是网络问题，大概率是版本锁死了。官方包名确实是 yiisoft/yii2-mongodb，但 2.5.x 要求 PHP ≥ 7.4 且 Yii2 ≥ 2.0.43；老项目用 PHP 7.3 + Yii2 2.0.35 的话，强行装 2.5.x 会直接报 dependency conflict。
- PHP 7.2–7.3 + Yii2 < 2.0.43 → 运行
composer require --prefer-dist yiisoft/yii2-mongodb:2.4.0 - PHP 7.4+ + Yii2 ≥ 2.0.43 → 用
composer require --prefer-dist yiisoft/yii2-mongodb:~2.5.0 - 装完检查
vendor/yiisoft/yii2-mongodb目录是否存在，再运行php -m | grep mongodb确认 PHP 扩展已启用（输出应为mongodb，不是mongo）
配置 mongodb 组件时 connectionString 格式错误
dsn 看似和 MySQL 一样，实则更敏感：末尾的数据库名是强制项，不带就连接成功但查不到集合；认证参数缺失会导致 Authentication failed；Docker 环境下还可能因 bindIp 限制连不上。
- 本地无认证：
mongodb://localhost:27017/myapp（/myapp不可省） - 带账号密码：
mongodb://myuser:mypass@localhost:27017/myapp?authSource=admin（authSource必须明确，通常为admin） - 配置 key 必须叫
mongodb，写在config/web.php的components下，否则 ActiveRecord 找不到连接实例
定义 MongoDB 模型时 _id 字段处理出错
新手常手动加 public $id 或重写 primaryKey() 返回 ['id']，结果插入失败、查询全空、甚至触发 Unknown method: getId()。MongoDB 的 _id 是 ObjectId 类型，Yii2-mongodb 已封装自动生成逻辑，你只需声明它是主键。
- 模型类继承
\yii\mongodb\ActiveRecord，不要声明_id属性 - 必须覆盖
primaryKey()方法：public static function primaryKey() { return ['_id']; } - 插入时不设
_id，驱动自动注入 ObjectId；如需字符串 ID（比如 UUID），在beforeSave()中赋值$this->_id = uniqid()即可
最容易被忽略的是：即使连接测试成功、模型定义看着没问题，只要 primaryKey() 没返回 ['_id']，所有基于 ActiveQuery 的查询（findOne()、findAll()）都会返回空数组，且不报错——它只是 quietly 不匹配任何文档。
