IP定位API完全指南：从原理到生产级部署的实战手册

写在前面

IP地理定位到底是怎么工作的

五款主流免费IP定位API横评

测试方法

测试结果

数据维度对比

生产环境接入方案

架构设计

用户请求 → 网关 → IP定位服务（本地缓存）→ 外部API
                    ↓
                  Redis缓存（24小时TTL）

这样做的好处：第一，外部API故障时缓存数据仍然可用；第二，大幅降低API调用量；第三，统一了不同API的返回格式。

#
代码实现


以下是一个生产级的IP定位服务封装：

class IPLocationService {
  constructor() {
    this.cache = new Map();
    this.cacheTTL = 86400000; // 24小时
    this.providers = [
      { name: 'ipinfo', endpoint: 'https://ipinfo.io', priority: 1 },
      { name: 'ip-api', endpoint: 'http://ip-api.com/json', priority: 2 },
    ];
    this.failover = { threshold: 3, cooldown: 300000 }; // 连续失败3次，冷却5分钟
    this.failureCount = {};
  }

  async lookup(ip) {
    // 1. 检查缓存
    const cached = this.cache.get(ip);
    if (cached && Date.now() - cached.timestamp < this.cacheTTL) {
      return cached.data;
    }

    // 2. 按优先级尝试不同API
    for (const provider of this.providers) {
      if (this.isProviderDown(provider.name)) continue;

      try {
        const data = await this.callProvider(provider, ip);
        this.cache.set(ip, { data, timestamp: Date.now() });
        this.resetFailure(provider.name);
        return data;
      } catch (error) {
        this.recordFailure(provider.name);
        continue;
      }
    }

    // 3. 所有API都失败，返回缓存（即使过期）
    if (cached) return cached.data;
    throw new Error('All IP lookup providers failed');
  }

  isProviderDown(name) {
    return this.failureCount[name] >= this.failover.threshold;
  }

  async callProvider(provider, ip) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 5000);

    try {
      const url = provider.name === 'ipinfo'
        ? `${provider.endpoint}/${ip}/json`
        : `${provider.endpoint}/${ip}`;

      const response = await fetch(url, {
        signal: controller.signal,
        headers: { 'Accept': 'application/json' }
      });
      clearTimeout(timeout);

      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return await response.json();
    } catch (error) {
      clearTimeout(timeout);
      throw error;
    }
  }
}

#
缓存策略建议


不同业务场景的缓存时长应该不同：

- 内容个性化推荐：缓存1-2小时，用户在不同时段可能在不同地点
- 风控反欺诈：缓存24-48小时，IP与账户的绑定关系相对稳定
- 数据分析统计：缓存7天，统计数据不需要实时更新
- 广告定向投放：缓存4-6小时，平衡精准度和性能

常见问题排查


Q: 同一个IP在不同API返回不同城市？

这是正常的。IP定位本身就不是精确科学，城市边界附近的IP尤其容易出现偏差。建议以一个API为准，不要混合使用多个API的结果。

Q: IPv6地址能定位吗？

大部分免费API对IPv6的支持不如IPv4。ipinfo.io对IPv6的支持最好，准确率能达到85%以上。如果你的用户群体中有较多IPv6用户（比如日本和德国），建议优先选择ipinfo.io。

Q: 如何处理局域网IP（192.168.x.x）？

局域网IP和保留地址无法通过公网API定位。在调用外部API之前，先用正则判断是否为私有地址，直接返回默认位置或跳过定位。

function isPrivateIP(ip) {
  const patterns = [
    /^10\./, /^172\.(1[6-9]|2[0-9]|3[01])\./,
    /^192\.168\./, /^127\./, /^::1$/
  ];
  return patterns.some(p => p.test(ip));
}

总结


选择IP定位API的关键不是看谁的功能列表最长，而是根据你的实际场景匹配。需要高精度选ipinfo.io，需要代理检测选ip-api.com，需要大量调用且不在意延迟选freeipapi.com。

更重要的是，生产环境中一定要做好缓存和故障切换。免费API的稳定性终究不如付费服务，但通过合理的架构设计，完全可以在保证可靠性的同时控制成本。Free API Hub上收录了多款IP定位API，都有完整的文档和在线测试工具，建议在正式接入前先在平台上测试一下效果。