yii2-mongodb安装失败主因是版本不匹配：php 7.2–7.3需用2.4.0，7.4+且yii2≥2.0.43才可用2.5.x；连接需正确配置dsn含数据库名及authsource；模型主键必须设为'_id'，查询须转objectid实例。
composer install yii2-mongodb 失败或找不到包
常见错误是直接执行 composer require --prefer-dist yiisoft/yii2-mongodb 却提示包不存在，因为官方已将该扩展迁移到 yiisoft/yii2-mongodb → 实际上这个命名是正确的，但问题往往出在 Yii2 版本和 PHP 版本不匹配。
关键点：yii2-mongodb 2.5.x 要求 PHP ≥ 7.4，且只兼容 Yii 2.0.43+；若你用的是较老的 Yii2（比如 2.0.30），必须降级到 2.4.0：
- PHP 7.2–7.3 → 用
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输出有mongodb（不是mongo）——这是 PHP MongoDB 驱动，不是扩展包
配置 mongodb 组件时 connectionString 写错格式
典型错误是把 MySQL 风格的 host:port 拼接套用过来，比如写成 mongodb://127.0.0.1:27017 看似对，但漏掉数据库名或认证参数，导致连接成功却查不到集合，或报 Authentication failed。
正确写法取决于部署场景：
- 本地无认证：
mongodb://127.0.0.1:27017/myapp（末尾/myapp是默认 database，必填） - 带用户名密码：
mongodb://myuser:mypass@127.0.0.1:27017/myapp?authSource=admin（authSource指定认证库，通常为admin） - Docker 或远程环境：确保端口映射开放、防火墙放行，且
bindIp在mongod.conf中包含对应 IP（不能只写127.0.0.1）
配置写在 config/web.php 的 components 下，key 必须叫 mongodb（框架约定），否则 ActiveRecord 找不到连接：
'mongodb' => [
'class' => '\yii\mongodb\Connection',
'dsn' => 'mongodb://localhost:27017/myapp',
],
定义 Mongo ActiveRecord 模型时 _id 字段处理不当
新手常以为要手动声明 _id 属性，或试图用 int 类型覆盖它，结果插入失败、查询返回空，甚至触发 BadMethodCallException: Unknown method。
MongoDB 的 _id 是 ObjectId，默认由驱动自动生成，Yii2-mongodb 已封装好逻辑：
- 模型类继承
\yii\mongodb\ActiveRecord，不用声明_id属性 - 主键必须设为
_id：在模型中加public static function primaryKey() { return ['_id']; } - 插入时留空
_id，驱动自动注入 ObjectId；如需自定义（比如用字符串 ID），可在beforeSave()中赋值：$this->_id = (string) new \MongoDB\BSON\ObjectId(); - 查询时用
findOne(['_id' => new \MongoDB\BSON\ObjectId('...')])，不能直接传字符串——除非你显式启用了autoId（不推荐）
find() 返回空或报 Call to a member function select() on null
这通常不是语法错，而是集合（collection）名没对上。Yii2-mongodb 默认按模型类名小写 + 复数规则找集合，比如 User 类对应 users 集合；但如果你的集合叫 user_info 或 members，就查不到。
解决方法只有显式指定：
- 在模型中重写
collectionName()方法：public static function collectionName() { return 'user_info'; } - 确保集合真实存在（用
mongo shell或 Studio 3T 确认），且当前用户有读权限 -
find()返回的是Query对象，不是数组；必须调用one()或all()才真正执行查询——漏掉会表现为“没报错但没数据” - 调试时可用
var_dump($query->createCommand()->getCommand());看生成的原始命令，确认数据库名、集合名、条件字段是否拼写一致
最易被忽略的是 ObjectId 的类型转换——传字符串 ID 查询前，几乎总要手动转成 MongoDB\BSON\ObjectId 实例；哪怕只是从 URL 参数取值，也得包一层 try/catch，否则一崩就是 500。
