Appearance
各省教材版本不一样,教育产品怎么按 IP 自动切换?PHP 实现与配置表
有个做小学口算训练的团队找过来,问题听起来很小:注册页有个"教材版本"下拉框,默认选中人教版,结果后台数据显示,河南、山东、江苏三地的用户里,将近四成在注册后一周内手动改过版本,改完的题量是没改的三倍。没改的那批人,很多是直接流失了——打开发现题目跟课本对不上,家长第一反应是"这软件不行"。
他们的下拉框有十一个选项,让一个三年级家长自己判断孩子用的是哪个版本,本来就是件不讲理的事。课本封面有出版社名字,但家长记不住;同一个市,语文和数学的版本还可能不一样。
所以这事真正的解法不是把下拉框做漂亮,是先替用户选对,再允许他改。而知情信息里最便宜的那个,是 IP 归属地。
一、教材版本的"碎",碎在学科而不是碎在省
动手之前得先搞清楚一件事:不是所有学科都需要按地区切。
义务教育阶段的语文、历史、道德与法治,从 2017 年起分三年统一换成了统编教材(人教社出版),全国一套,没有地区差异。这三科你要做地区映射,纯属给自己找麻烦。
真正分版本的是数学、英语、科学、音乐、美术这些。数学最典型:人教、北师大、苏教、沪教、青岛、西师、冀教、浙教、湘教……一个省用哪套,跟当地的教研传统、早年的课改实验区有关。
碎到什么程度?举几个常见的:
- 江苏数学主流是苏教版,但省内部分城市用北师大版或人教版;
- 山东数学常见青岛版,也有地市用人教版;
- 北京数学,不同区用人教版和北师大版都有;
- 上海是独立体系,沪教版,跟全国都不接;
- 重庆数学常见西师版。
再往下还有年级差异:同一学科,一二年级和五六年级版本可能不同(尤其是英语起点年级)。
这意味着两件事:一是配置表必须做到「学科 × 地区」两级,不能只按省;二是任何自动判断都只能是默认值,必须能被用户覆盖。指望靠一个省名把版本猜准,是不现实的。
二、方案:四级优先,把"猜"标出来
解析顺序定成这样,从上到下:
- 用户自己选的——最高优先级,只要他选过,永远不再用 IP 覆盖;
- 城市级配置——计划单列市、教材改革试点市,单独配(深圳的英语、青岛的数学、大连的数学都属于这类);
- 省级默认——省里大多数地市的版本;
- 兜底——人教版,同时把结果标记成
default,前端提示"请确认孩子的教材版本"。
关键是第 4 步的 source 字段。它决定了前端怎么展示:
source | 前端表现 |
|---|---|
user | 保持用户选择,不提示 |
city / province | 显示"已按你所在地区预选:苏教版(数学)",旁边一个小链接「不对?改一下」 |
default | 不做预选,直接把下拉框展开,文案改成"请选择孩子的教材版本" |
这个区分很重要。default 状态下如果也显示"已按你所在地区预选",等于在撒谎,用户改选率反而更高。
三、PHP 实现
代码分三块:取真实 IP、查归属地(带文件缓存和限速)、按配置表解析。跑在 PHP 8 上,只依赖 curl。
php
<?php
declare(strict_types=1);
const IP9_API = 'https://ip9.com.cn/get';
const CACHE_TTL = 86400; // 归属地一天查一次足够
// 版本字典:code => 展示名,运营在后台维护
const EDITIONS = [
'pep' => '人教版', 'bsd' => '北师大版', 'sj' => '苏教版',
'sh' => '沪教版', 'yj' => '粤教版', 'zj' => '浙教版',
'xj' => '湘教版', 'hb' => '冀教版', 'qd' => '青岛版',
'xs' => '西师版', 'wys' => '外研版',
];
// 省级默认值:只对"分版本"的学科配,语文/历史/道法不用配
const PROVINCE_DEFAULT = [
'北京' => ['math' => 'bsd', 'chinese' => 'pep', 'english' => 'pep'],
'上海' => ['math' => 'sh', 'chinese' => 'sh', 'english' => 'sh'],
'江苏' => ['math' => 'sj', 'chinese' => 'pep', 'english' => 'yj'],
'浙江' => ['math' => 'zj', 'chinese' => 'pep', 'english' => 'pep'],
'广东' => ['math' => 'pep', 'chinese' => 'pep', 'english' => 'yj'],
'山东' => ['math' => 'qd', 'chinese' => 'pep', 'english' => 'pep'],
'河北' => ['math' => 'hb', 'chinese' => 'pep', 'english' => 'pep'],
'湖南' => ['math' => 'pep', 'chinese' => 'pep', 'english' => 'xj'],
'重庆' => ['math' => 'xs', 'chinese' => 'pep', 'english' => 'pep'],
'四川' => ['math' => 'pep', 'chinese' => 'pep', 'english' => 'pep'],
];
// 城市级覆盖:key 用接口返回的 city_code(小写拼音),比中文城市名稳
const CITY_OVERRIDE = [
'shenzhen' => ['english' => 'yj'],
'qingdao' => ['math' => 'qd'],
'dalian' => ['math' => 'bsd'],
];
final class TextbookResolver
{
private string $cacheDir;
private float $lastCallAt = 0.0;
public function __construct(string $cacheDir)
{
$this->cacheDir = rtrim($cacheDir, '/');
if (!is_dir($this->cacheDir)) {
mkdir($this->cacheDir, 0775, true);
}
}
/** 取客户端 IP:XFF 只取首段,内网和保留地址返回 null。 */
public static function clientIp(array $server): ?string
{
$raw = $server['HTTP_X_FORWARDED_FOR'] ?? $server['REMOTE_ADDR'] ?? '';
$ip = trim(explode(',', $raw)[0]);
if (str_starts_with($ip, '::ffff:')) {
$ip = substr($ip, 7); // IPv4-mapped IPv6
}
if ($ip === '' || filter_var($ip, FILTER_VALIDATE_IP,
FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) === false) {
return null;
}
return $ip;
}
/** 查归属地:文件缓存 24 小时,429 退避一次,非法 IP 直接放弃。 */
public function geo(string $ip): ?array
{
$file = $this->cacheDir . '/' . md5($ip) . '.json';
if (is_file($file) && time() - filemtime($file) < CACHE_TTL) {
$cached = json_decode((string) file_get_contents($file), true);
if (is_array($cached)) {
return $cached;
}
}
// 免费版 60 次/分钟,相邻请求留 1.05 秒间隔
$wait = 1.05 - (microtime(true) - $this->lastCallAt);
if ($wait > 0) {
usleep((int) ($wait * 1_000_000));
}
$this->lastCallAt = microtime(true);
$url = IP9_API . '?ip=' . urlencode($ip);
for ($try = 0; $try < 2; $try++) {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 2,
CURLOPT_TIMEOUT => 3,
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($code === 429) {
usleep(1_000_000);
continue;
}
if ($body === false || $code !== 200) {
return null;
}
$json = json_decode($body, true);
if (!is_array($json) || ($json['ret'] ?? 0) !== 200) {
return null;
}
$data = $json['data'];
file_put_contents($file, json_encode($data));
return $data;
}
return null;
}
/**
* $userChoice 有值就直接用,IP 只做默认值,永远不覆盖手动选择。
*/
public function resolve(?string $ip, string $subject = 'math', ?string $userChoice = null): array
{
if ($userChoice !== null && isset(EDITIONS[$userChoice])) {
return ['edition' => $userChoice, 'name' => EDITIONS[$userChoice],
'source' => 'user', 'province' => null, 'city' => null];
}
$geo = $ip ? $this->geo($ip) : null;
$prov = $geo['prov'] ?? '';
$city = $geo['city'] ?? '';
$cityKey = $geo['city_code'] ?? '';
$edition = null;
$source = 'default';
if ($cityKey !== '' && isset(CITY_OVERRIDE[$cityKey][$subject])) {
$edition = CITY_OVERRIDE[$cityKey][$subject];
$source = 'city';
} elseif ($prov !== '' && isset(PROVINCE_DEFAULT[$prov][$subject])) {
$edition = PROVINCE_DEFAULT[$prov][$subject];
$source = 'province';
}
$edition = $edition ?? 'pep'; // 兜底,但一定要标出来
return ['edition' => $edition, 'name' => EDITIONS[$edition] ?? $edition,
'source' => $source, 'province' => $prov, 'city' => $city];
}
}命令行跑一遍,接口是真实调用的:
IP | 省 | 市 | 数学默认 | 来源 | 说明
202.96.209.133 | 上海 | 上海 | 沪教版 | province |
202.96.128.86 | 广东 | 广州 | 人教版 | province |
202.102.128.68 | 山东 | 济南 | 青岛版 | province |
219.141.136.10 | 北京 | 北京 | 北师大版 | province |
61.139.2.69 | 四川 | 成都 | 人教版 | province |
2408:8000:1100::1 | 北京 | 北京 | 北师大版 | province |
1.1.1.1 | - | - | 人教版 | default | 未命中,兜底需引导用户手选三个细节值得说:
IPv6 是同一套逻辑。 2408:8000:1100::1 返回「北京 / 北京 / 中国联通城域网」,跟 IPv4 结果一致,不用为移动网络单独写分支。早期很多教育产品只处理了 IPv4,结果安卓移动端用户全都落到 default,改选率高得离谱,还查不出原因。
city_code 比中文城市名稳。 接口返回的 city_code 是小写拼音(hangzhou、shenzhen),拿它做覆盖表的 key,不会被"市/地区/自治州"这类后缀差异坑到。
境外 IP 一定落到 default。 1.1.1.1 是澳大利亚,prov 和 city 都是空。海外华人子女、国际学校用户确实存在,但教材体系跟国内完全不同,这时候正确做法是让用户自己选或者选课程体系,不是硬猜一个「人教版」。
四、真正有用的那一步:用"改选率"反过来修配置
配置表刚上线一定不准。别指望运营拍脑袋拍对,让数据说话:
给每次「用户手动改选版本」打一条埋点,带上服务端算出来的省份和改选前的默认值。按省聚合,算两个指标:
- 改选率 = 改选人数 / 该省曝光人数;
- 流向 = 改选后集中去了哪个版本。
如果一个省的改选率明显高于全国均值(比如全国 12%,某省 45%),而且改选后的流向高度集中(八成流向人教版),那基本可以断定:这个省的默认配置配错了。把配置改掉,两周后再看改选率有没有掉下来。
这套闭环比任何"权威教材版本对照表"都可靠——因为对照表会过时(教材三五年一换),而你的用户每天都在给你标注正确答案。
顺带说,曝光埋点里不要存完整 IP。存省份、城市和 source 就够了,IP 用完即弃。这既是《个人信息保护法》里最小必要原则的要求,也省掉一堆存储和脱敏的麻烦——你需要的粒度本来就是省,不是个人。
五、几个会翻车的地方
VPN 和公司网络会让默认值偏。 家长在公司加班时给孩子注册,出口 IP 是公司总部所在地(很多集团总部在北京、上海)。这类用户占比不高但投诉很响,所以那个「不对?改一下」的入口必须在首屏可见,不能藏在设置里。
双城家庭。 户籍在河南、在江苏上学,或者反过来。IP 只能判断"现在在哪里上网",判断不了"在哪里上学"。所以配置表再准,也要留手动入口。
别把映射表写进前端包。 见过把十一个版本和省份映射硬编码在小程序里的,教材一改版就得重新提审发版,两周才能上线。这张表放服务端,前端只拿结果。
学科粒度要一开始就留出来。 如果表结构是 省 => 版本,后面加英语版本时会想哭。哪怕暂时只有数学,也写成 省 => {学科: 版本}。
缓存别只放进程内。 PHP-FPM 每个 worker 的进程内缓存互相看不见,热 IP 会被重复查;文件缓存或 Redis 都行,key 用 IP,TTL 一天。免费版 60 次/分钟的限制,配上一天缓存,日活一两万的产品基本碰不到上限。
总结
这件事的技术含量不高,思路值钱:IP 归属地给出一个"大概率对"的默认值,source 字段诚实地告诉前端这个值有多可信,用户的每一次改选都变成修配置的依据。
接口就是 https://ip9.com.cn/get?ip=<ip>,返回 prov、city、city_code 这些字段,IPv4/IPv6 都支持,不传 ip 查当前请求方,免费版 60 次/分钟、不用注册。要区县级精度或者 ip_type 区分家宽/机房,那是 VIP 版的能力,教材场景一般用不上——省级加城市级覆盖已经够。
最后提醒一句:教材版本以当地教育局和学校实际用书为准,任何配置表都只是默认值。把这个预期写进产品文案里,比多配十个省都管用。