node-ip2region

IP 地址到区域运营商 IP（支持 IPv6） to region on Node.js

安装使用使用

$ npm install ip2region --save

// const IP2Region = require('ip2region').default;
import IP2Region from "ip2region";
const query = new IP2Region();
const res = query.search('120.24.78.68');
console.log(res);
> { country: '中国', province: '广东省', city: '深圳市', isp: '阿里云' }
const res2 = query.search('240e:47d:c20:1627:30a3:ba0d:a5e6:ec19');
console.log(res2);
> { country: "中国", province: "广东省", city: "", isp: "中国电信" }

CommonJS、ESM 和 TypeScript

原生 Node.js ESM（.mjs 或 package.json 中设置 "type": "module"）直接使用 import IP2Region from "ip2region"，无需再取 .default。旧的 ESM imported.default 绕过写法保留为兼容别名，建议新代码直接使用默认导入。 CommonJS 保持原来的 const IP2Region = require("ip2region").default 用法。 两种入口使用同一个类和实现。TypeScript 同时提供默认类导出及 IP2RegionOpts、IP2RegionResult 类型，支持传统 moduleResolution: "node" 以及 Node16、NodeNext 和 bundler 模式。

开发验证

pnpm install --frozen-lockfile
npm test -- --runInBand
npm run compile
npm run test:package

test:package 构建后执行 npm pack，在临时目录离线安装 tarball，验证 CommonJS、原生 ESM、 动态导入、TypeScript 类型及编译后的消费者运行行为。发布生命周期不会在该测试中执行。

配置

• ipv4db: ipv4 数据库地址
• ipv6db: ipv6 数据库地址
• disableIpv6: 关闭 ipv6 查询功能（减少内存占用）

import IP2Region from "ip2region";
const query = new IP2Region({
  ipv4db: "/tmp/db4.db",
  ipv6db: "/tmp/db6.db",
  disableIpv6: true,
});

自行扩充或替换数据库

可以通过 ipv4db / ipv6db 加载自行生成的兼容数据库。它们会替换对应的内置库， 不会自动合并或在未命中时回退到内置库。本包是只读查询器，不提供向二进制数据库追加记录的 API。 数据库在构造时读入内存；更新文件后需要重新创建实例。

IPv4

本包读取 ip2region 1.x 的旧版 .db 格式，不支持 2.x/3.x 的 .xdb， 也不能将 CSV、JSON、文本文件或 .xdb 改名为 .db 后使用。

可使用上游 v1.9.0 的 Java maker 重新生成数据库（需要 Java）：

1. 检出上游 lionsoul2014/ip2region 的 v1.9.0 标签。

2. 复制该版本的 data/ip.merge.txt 为自己的源文件，按需修改或加入 IP 范围。 每行格式为 起始IPv4|结束IPv4|国家|区域|省份|城市|ISP，例如： 192.0.2.0|192.0.2.255|测试国|0|测试省|测试市|测试运营商。 按 IP 数值升序排列，范围不可重叠；覆盖现有范围时先拆分旧范围，不能直接追加重叠记录。 需要保留原有查询结果时，保留源文件中的其他范围。未知字段用 0。

3. 在上游仓库根目录运行（-dst 是已存在的输出目录）：

   mkdir -p custom-data
   java -jar maker/java/dbMaker-1.2.2.jar \
     -src ./my-ip.merge.txt \
     -region ./data/global_region.csv \
     -dst ./custom-data

   输出为 custom-data/ip2region.db。地域 ID 映射使用 global_region.csv； 如需自定义城市 ID，也应按上游格式维护该文件。

4. 将生成的库放在应用自己的数据目录，通过绝对路径加载：

   const IP2Region = require("ip2region").default;
   const { resolve } = require("path");
   
   const query = new IP2Region({
     ipv4db: resolve("./custom-data/ip2region.db"),
     disableIpv6: true,
   });
   console.log(query.search("192.0.2.42"));

未覆盖的 IPv4 地址返回 null。不要修改 node_modules 内的数据库，以免安装或升级覆盖。 为兼容已有用法，相对数据库路径仍相对于本包实现文件所在目录解析，不是应用的工作目录； 推荐如上使用 resolve() 明确生成绝对路径。

IPv6

ipv6db 需要兼容现有 ipv6wry.db 的 IPDB 二进制格式，它与 IPv4 .db 不同， 不能用上面的 IPv4 maker 生成。已有兼容库可通过 ipv6db: resolve("./custom-data/ipv6wry.db") 加载；本包不提供 IPv6 数据生成器。IPv4 映射地址等查询使用同一实例的 IPv4 数据库。 只扩充 IPv4 时可省略 ipv6db 继续使用内置 IPv6 库，或设置 disableIpv6: true。 扩充数据的来源、准确性与再分发许可由使用者自行选择和维护。