phone2region

📱 轻量级的中国手机号归属地查询库 - TypeScript 编写，零依赖

✨ 特性

• 🚀 高性能：使用二分查找算法，毫秒级查询速度
• 📦 零依赖：不依赖任何第三方库
• 💪 类型安全：完整的 TypeScript 类型定义
• 🎯 精准数据：包含运营商、省份、城市、邮编、区号等完整信息
• 🔄 支持虚拟运营商：覆盖移动、联通、电信及其虚拟运营商
• 📱 灵活输入：支持数字或字符串格式的手机号

📦 安装

npm install phone2region

或使用 yarn：

yarn add phone2region

或使用 pnpm：

pnpm add phone2region

🚀 快速开始

ES6 模块导入

import find from 'phone2region';
// 或
import { find } from 'phone2region';

const result = find(13800138000);
console.log(result);

CommonJS 导入

const find = require('phone2region').default;
// 或
const { find } = require('phone2region');

const result = find(13800138000);
console.log(result);

📖 使用示例

基础用法

import find from 'phone2region';

// 使用数字格式
const info1 = find(13800138000);
console.log(info1);
// 输出：
// {
//   phone: 13800138000,
//   op: '移动',
//   province: '上海',
//   city: '上海',
//   zipCode: '200000',
//   areaCode: '021'
// }

// 使用字符串格式
const info2 = find('15211470001');
console.log(info2);

// 支持短号码（前7位）
const info3 = find(1713200);
console.log(info3);

TypeScript 类型支持

import find, { PhoneInfo } from 'phone2region';

const getPhoneLocation = (phone: number | string): PhoneInfo => {
  return find(phone);
};

const info = getPhoneLocation(13800138000);

// 类型安全访问
console.log(`${info.province}${info.city} - ${info.op}`);
console.log(`邮编：${info.zipCode}，区号：${info.areaCode}`);

📚 API 文档

find(phone: number | string): PhoneInfo

查询手机号归属地信息。

参数

• phone - 手机号码，支持以下格式：
  • 完整的 11 位手机号（数字或字符串）：13800138000 或 "13800138000"
  • 前 7 位号码：1380013
  • 字符串格式："13800138000"

返回值

返回 PhoneInfo 对象，包含以下字段：

interface PhoneInfo {
  phone: number | string;  // 原始手机号
  op: string;              // 运营商（移动/联通/电信/虚拟运营商）
  province: string;        // 省份
  city: string;            // 城市
  zipCode: string;         // 邮政编码
  areaCode: string;        // 区号
}

运营商类型

• 移动 - 中国移动
• 联通 - 中国联通
• 电信 - 中国电信
• 移动虚拟运营商
• 联通虚拟运营商
• 电信虚拟运营商
• 异常 - 未找到或无效号码

🗂️ 数据来源

数据来源于 pangongzi/phone 项目，感谢原作者的贡献。

数据文件 phone.dat 采用紧凑的二进制格式存储，包含：

• 手机号段索引（使用前 7 位作为索引）
• 归属地信息（省份、城市、邮编、区号）
• 运营商类型标识

🛠️ 开发

克隆仓库

git clone https://github.com/iBugCode/phone2region.git
cd phone2region

安装依赖

npm install

构建项目

npm run build

运行测试

npm test

📦 发布

项目已配置自动构建流程：

npm run prepublishOnly  # 发布前自动构建
npm publish             # 发布到 npm

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 提交 Pull Request

📄 许可证

MIT © [email protected]

🔗 相关链接

• GitHub 仓库
• NPM 包
• 问题反馈

⚠️ 注意事项

• 数据库可能不包含最新分配的手机号段，建议定期更新
• 查询结果基于手机号前 7 位，准确率取决于数据源
• 虚拟运营商号段可能存在一定延迟

📝 更新日志

0.0.3

• TypeScript 重写
• 完整的类型定义
• 优化查询性能
• 添加完整文档

如果觉得有用，请给个 ⭐️ Star 支持一下！