PHPackages                             zoujingli/ip2region - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. zoujingli/ip2region

ActiveLibrary[Utility & Helpers](/categories/utility)

zoujingli/ip2region
===================

PHP IP 地理位置查询库，基于 ip2region XDB，支持 IPv4/IPv6、内置 IPv4 数据库、IPv6 按需下载和多种缓存策略

v3.0.15(3mo ago)1.4k491.4k↑12.4%20920Apache-2.0PHPPHP >=7.1.0

Since Mar 22Pushed 1mo ago29 watchersCompare

[ Source](https://github.com/zoujingli/ip2region)[ Packagist](https://packagist.org/packages/zoujingli/ip2region)[ Docs](https://github.com/zoujingli/Ip2Region)[ RSS](/packages/zoujingli-ip2region/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (10)DependenciesVersions (42)Used By (20)

[![Latest Stable Version](https://camo.githubusercontent.com/26f597857d6aff2815ddb28ef8920d0d33aa282726fa9aab324bfb3bbe132b21/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f762f737461626c65)](https://packagist.org/packages/zoujingli/ip2region)[![Total Downloads](https://camo.githubusercontent.com/fea5425209aec0e2b48e106321adfd87d5e439382fe50beae8b657c0560dfa66/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f646f776e6c6f616473)](https://packagist.org/packages/zoujingli/ip2region)[![Monthly Downloads](https://camo.githubusercontent.com/38e079273c4a4ab6b7d0cf68ae7d36788ee3759693383cc2229ccfd85dcb8164/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f642f6d6f6e74686c79)](https://packagist.org/packages/zoujingli/ip2region)[![Daily Downloads](https://camo.githubusercontent.com/fcbcd1770c5d6b8906001b5b70a8d93cdb0e853f02f421639105d6b65f974ec7/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f642f6461696c79)](https://packagist.org/packages/zoujingli/ip2region)[![PHP Version Require](https://camo.githubusercontent.com/efdb9aa0e58f1f5208a3f302bec5845c6c9b8df83aca6461c8735482a602570d/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f726571756972652f706870)](https://packagist.org/packages/zoujingli/ip2region)[![License](https://camo.githubusercontent.com/ee87b0a81848a3a55eab7bbf50e91082e0771e55c7f22606be589d7ed1f0e03a/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f6c6963656e7365)](https://packagist.org/packages/zoujingli/ip2region)

🌍 ip2region for PHP
===================

[](#-ip2region-for-php)

`zoujingli/ip2region` 是一个基于 [ip2region](https://github.com/lionsoul2014/ip2region) XDB 数据格式的 PHP IP 地理位置查询库。它提供函数式和面向对象两种调用方式，支持 IPv4、IPv6、批量查询、三种缓存策略和特殊用途地址识别。

> ✅ **IPv4 开箱即用**：仓库内置 `db/ip2region_v4.xdb`。
>
> ⚠️ **IPv6 按需启用**：普通 IPv6 查询需要额外准备 `ip2region_v6.xdb`。
>
> 🧩 **零额外扩展依赖**：PHP 7.1+ 即可使用。

🧭 快速导航
------

[](#-快速导航)

- 主要能力
- 安装
- 数据库准备
- 快速开始
- API 参考
- 特殊用途地址
- 命令行工具
- 测试与性能
- 故障排除

✨ 主要能力
------

[](#-主要能力)

图标能力说明🚀IPv4 查询内置 `db/ip2region_v4.xdb`，安装后即可查询🌐IPv6 查询支持 IPv6 XDB，数据库按需下载或自定义传入🔌调用方式支持 `ip2region()` 全局函数和 `Ip2Region` 类⚙️缓存策略支持 `file`、`vectorIndex`、`content` 三种模式🛡️特殊地址`simple()` 优先识别私网、回环、链路本地、文档测试、组播、保留地址等🧰数据库工具提供 `ip2down` 下载、查看、测试、清理数据库🧩运行环境PHP 7.1+，纯 PHP 实现，无额外扩展依赖📦 安装
----

[](#-安装)

```
composer require zoujingli/ip2region:^3.0
```

源码仓库开发或验证时，先生成 Composer 自动加载文件：

```
composer install
```

🗄️ 数据库准备
--------

[](#️-数据库准备)

### 🔎 数据库查找顺序

[](#-数据库查找顺序)

`Ip2Region` 会按以下顺序查找数据库文件：

1. **自定义路径**：构造函数传入的 `$dbPathV4`、`$dbPathV6`
2. **下载目录**：`vendor/bin/ip2data/ip2region_v4.xdb`、`vendor/bin/ip2data/ip2region_v6.xdb`
3. **包内默认目录**：`db/ip2region_v4.xdb`、`db/ip2region_v6.xdb`

IPv4 数据库已随包发布。IPv6 数据库默认不内置，需要下载到 `vendor/bin/ip2data/`、手动放入 `db/`，或通过构造函数提供绝对路径。

### 📥 下载 IPv6 数据库

[](#-下载-ipv6-数据库)

推荐使用内置工具：

```
./vendor/bin/ip2down download v6
```

常用数据库命令：

```
# 下载 IPv6 数据库
composer download:v6

# 下载 IPv4 和 IPv6 数据库
composer download

# 查看已下载的数据库
./vendor/bin/ip2down list

# 测试数据库查询能力
./vendor/bin/ip2down test

# 清理 vendor/bin/ip2data/ 下的下载文件，不会删除包内 db/ 文件
./vendor/bin/ip2down clear
```

源码仓库中如果没有 `vendor/bin/ip2down`，可以直接运行：

```
php bin/ip2down download v6
```

也可以手动下载官方 XDB 文件：

```
mkdir -p db
curl -L -o db/ip2region_v6.xdb \
  "https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v6.xdb"
```

> 💡 如果直连 GitHub 不稳定，可以改用你自己的镜像或代理地址。请确认下载到的是 `.xdb` 文件，不是 HTML 错误页。

🚀 快速开始
------

[](#-快速开始)

### ⚡ 全局函数

[](#-全局函数)

```