直接用 composer require geoip2/geoip2 可安装，但需手动下载 GeoLite2-City.mmdb 数据库文件并配置绝对路径，确保 cURL、JSON 扩展启用且 PHP ≥ 7.2；Laravel 中应通过 Service Provider 单例绑定 Reader，避免每次请求重复实例化。
直接用 composer require geoip2/geoip2 就能装上，但实际集成时经常卡在数据文件路径、Laravel 适配或 API 调用报错上。
安装命令与基础依赖确认
GeoIP2 官方库是纯 PHP 实现，不依赖系统级 GeoIP 库，但需要 cURL 和 json 扩展启用。运行前先检查：
-
php -m | grep curl确认 cURL 已加载 -
php -m | grep json确认 JSON 支持正常 - PHP 版本需 ≥ 7.2（官方最低要求，8.0+ 更稳妥）
执行安装：
composer require geoip2/geoip2
安装后会自动注册 Composer 自动加载，无需手动 require。
下载并配置 GeoLite2 数据库文件
Composer 只装 PHP SDK，不带 IP 库数据。必须单独下载 GeoLite2-City.mmdb 或 GeoLite2-Country.mmdb，否则实例化时会抛出 MaxMind\Db\Reader\Exception\InvalidDatabaseException。
- 去 MaxMind 官网免费注册，获取 License Key
- 用
curl或网页下载对应.mmdb文件（推荐放项目根目录下的storage/geoip/） - 确保 Web 服务器有读取权限：
chmod 644 storage/geoip/GeoLite2-City.mmdb
注意：不能用旧版 .dat 格式，geoip2/geoip2 v3+ 仅支持 .mmdb。
在 Laravel 中安全调用 GeoIP2 查询
Laravel 没有内置绑定，别直接 new GeoIp2\Database\Reader 在控制器里——每次请求都打开文件会拖慢性能，也容易触发 open_basedir 限制。
- 把 Reader 实例化移到 Service Provider 的
boot()或使用 Laravel 的容器单例绑定 - 路径必须用绝对路径：
base_path('storage/geoip/GeoLite2-City.mmdb')，相对路径会失败 - 查询示例（带异常兜底）：
$reader = new \GeoIp2\Database\Reader(base_path('storage/geoip/GeoLite2-City.mmdb'));
try {
$record = $reader->city('8.8.8.8');
echo $record->country->name; // United States
} catch (\GeoIp2\Exception\AddressNotFoundException $e) {
// IP 不在库中，如内网地址、私有地址段
}
常见报错与绕过方案
最常遇到的不是安装失败，而是运行时报错：
-
MaxMind\Db\Reader\Exception\InvalidDatabaseException→ 数据库文件损坏、路径错、非 .mmdb 格式 -
Permission denied→ 文件权限不足，或 SELinux/AppArmor 阻止 PHP 读取 -
AddressNotFoundException→ 正常现象，不代表库有问题，IPv6 / 私有 IP / 新分配 IP 常无记录 - Laravel Mix 编译后找不到类？→ 确保
composer dump-autoload -o重生成优化加载器
如果只是轻量查国家码，不用城市级精度，可改用更小的 GeoLite2-Country.mmdb（约 5MB），加载更快，内存占用更低。
