必须用yiisoft/yii2-mongodb扩展并安装PHP原生mongodb驱动；版本需匹配：PHP7.2–7.3+Yii2.0.30–42用2.4.0，PHP7.4+且Yii≥2.0.43用~2.5.0；配置key必须为mongodb，DSN末尾须带数据库名，模型主键必须设为'_id'且不手动声明。
Yii 框架操作 MongoDB 的核心路径很明确：必须用 yiisoft/yii2-mongodb 扩展，且不能跳过 PHP 原生 mongodb 驱动（不是已废弃的 mongo）。直接写原生驱动代码或混用旧版 EMongoDB 类，90% 会卡在连接或查询阶段。
composer require 失败或找不到包怎么办
错误常发生在版本错配。官方扩展已迁移到 yiisoft/yii2-mongodb，但不兼容所有环境：
- PHP 7.2–7.3 + Yii 2.0.30～2.0.42 → 必须指定
2.4.0：composer require --prefer-dist yiisoft/yii2-mongodb:2.4.0 - PHP 7.4+ + Yii ≥ 2.0.43 → 用
~2.5.0或~3.0.0（注意：3.x 要求 Yii 2.0.46+） - 装完后检查
vendor/yiisoft/yii2-mongodb是否存在；再运行php -m | grep mongodb，输出必须含mongodb（小写，无mongo）
mongodb 组件配置写在哪、怎么写才生效
配置必须放在 config/web.php（或 config/main.php）的 'components' 数组里，且 key 名严格为 mongodb —— 框架内部硬编码查找这个键名，写成 mongo 或 db_mongo 都会导致 ActiveRecord 找不到连接。
- 本地无认证：
mongodb://localhost:27017/myapp（末尾/myapp是数据库名，不可省略） - 带账号密码：
mongodb://myuser:mypass@localhost:27017/myapp?authSource=admin（authSource必须显式指定，通常为admin） - Docker/远程部署时，确保
mongod.conf中bindIp包含对应 IP，不能只写127.0.0.1
ActiveRecord 模型里 _id 字段怎么处理
新手最容易在这里报 BadMethodCallException: Unknown method 或插入后查不到数据。根本原因是误以为要手动声明 _id 属性，或试图用整数覆盖它。
- 模型类继承
\yii\mongodb\ActiveRecord，**不要声明public $_id** - 必须重写
primaryKey()：public static function primaryKey() { return ['_id']; } - 插入时完全不设
_id，驱动自动注入ObjectId；如需字符串 ID（比如 UUID），可在beforeSave()中赋值：$this->_id = (string) new \MongoDB\BSON\ObjectId(); -
findOne()、findByPk()等方法传入的主键值，必须是ObjectId实例或合法字符串，不能传整数
聚合查询和 update 操作容易踩哪些坑
Yii2-mongodb 对聚合和更新操作做了封装，但底层仍依赖 MongoDB 原生命令，参数格式稍有偏差就会静默失败或返回空结果。
- 聚合必须用
\yii\mongodb\Query实例调用aggregate()，不能用find()->where(...)->aggregate(...)——where()在聚合 pipeline 前就失效了 -
updateAll()的更新文档必须用 MongoDB 运算符包裹，例如：['$set' => ['status' => 'done']]，直接传['status' => 'done']会覆盖整个文档 -
$push、$addToSet等操作要求目标字段是数组，否则报错；用前先确认 schema 或加$type判断 - 批量写入（如
batchInsert）不触发模型验证，需自行校验数据结构
最常被忽略的是：所有 ObjectId 相关操作（查询、更新、删除）都依赖 MongoDB\BSON\ObjectId 类，而该类由 PHP mongodb 驱动提供 —— 如果只装了扩展没装驱动，或驱动版本太低（new ObjectId('...') 会直接 fatal error。
