简介：这是一份面向前端开发者与轻量级Web项目实践者的手机话费余额实时查询解决方案，聚焦三大运营商（移动、电信、联通）的免验证码自助查询需求，特别适用于需快速集成话费查询功能的个人项目、教学演示或小型工具站。资源包共6个文件，含1个核心HTML页面（提供用户交互入口）、2个JS脚本（封装API调用与运营商自动识别逻辑）、1个CSS样式文件（基于Bootstrap精简定制）及2张界面截图，整体仅133KB，轻量易部署。已有613人学习下载，反映出其在低门槛API实践场景中的实用热度。使用者可直接运行HTML页面，替换源码中apiKey即可调用真实运营商接口；自动识别机制覆盖常规号码，携号转网用户仅需手动切换运营商标签；配套截图直观展示查询流程与结果样式，降低理解与调试成本。
1. 话费余额查询不是“爬虫玩具”，而是运营商级数据通道的轻量封装
你有没有试过在凌晨三点收到一条短信：“您的账户余额不足10元”？但当你打开官方App，却发现余额明明还有86元——这种延迟、错漏、多端不一致，正是传统话费查询体验的常态。而这个项目，把三大运营商（移动、电信、联通）的话费余额查询能力，压缩进一个纯前端 HTML 页面里：不依赖后端服务、不调用第三方代理、不弹验证码、不走 App SDK，只靠浏览器发起请求，5秒内返回真实余额、剩余流量、套餐有效期三要素。它不是教你怎么写爬虫，而是直接复用了运营商官网未公开但长期稳定的内部查询接口（HTTP+JSON），并做了防重放、会话保活、UA指纹适配三层封装。适合两类人：一是需要嵌入自助终端、物业大屏、校园一卡通系统的嵌入式开发者；二是想绕过App审核周期、快速上线“话费提醒”功能的SaaS产品同学。别被“HTML源码”四个字骗了——它背后是一套可部署、可监控、可灰度的轻量级通信协议栈。
2. 技术栈与架构设计：为什么不用Node.js做后端？因为运营商接口本身就不需要
这个项目最反直觉的设计选择，是全程无服务端。很多人第一反应是：“查话费怎么可能不走后端？运营商肯定有Referer校验、IP限频、Token过期”。但实测发现：三大运营商PC官网的余额查询接口，本质是面向浏览器的AJAX请求，只要满足三个条件就能直连：
- 请求头中
Origin和Referer必须指向其官网域名（如https://www.10086.cn）； - Cookie 中必须携带有效的登录态（
JSESSIONID+loginToken）； - 请求参数需经简单时间戳+随机数签名（非RSA，是MD5(base64(手机号+时间戳+salt))）。
项目用纯前端实现，恰恰是因为运营商没设防——他们默认“能拿到这些Cookie的人，已经登录成功了”。所以整个架构极简：
[用户浏览器] ↓ HTTPS GET/POST（带Origin/Referer/Cookie） [运营商官网查询接口] ↓ JSON响应（含余额、流量、有效期） [前端JS解析+渲染]没有Nginx反向代理，没有JWT签发，没有Redis缓存。所有逻辑压在query-balance.js里，不到300行。技术选型上，它刻意避开现代框架：
- 不用Vue/React：避免打包体积和运行时开销，终端设备内存常不足128MB；
- 不用Axios：改用原生
fetch+AbortController，规避其对credentials: 'include'的兼容性陷阱； - 不用Webpack：用
esbuild --minify一键压缩，最终HTML+JS+CSS总大小仅217KB。
这种“退回到2012年”的技术选择，不是怀旧，而是为适配老旧Android 4.4平板、Windows CE工控机、国产信创终端等真实部署环境。我去年在某高校后勤系统落地时，就因强行引入Vue导致海思Hi3516芯片设备白屏——后来换回这个纯HTML方案，三天上线。
2.1 核心目录结构：五个文件撑起全部功能
项目解压后只有5个文件，但每个都承担明确职责：
| 文件名 | 类型 | 关键作用 | 是否可删 |
|---|---|---|---|
index.html | HTML | 唯一入口页，含表单、结果区、加载动画 | ❌ 不可删 |
query-balance.js | JS | 主逻辑：拼参、签名、fetch、错误分类 | ❌ 不可删 |
carrier-config.json | JSON | 三大运营商接口URL、签名salt、字段映射规则 | ✅ 可替换为JS对象 |
style.css | CSS | 响应式布局，适配7寸~24寸屏幕，支持深色模式切换 | ✅ 可精简 |
README.md | 文档 | 部署说明、参数含义、常见报错代码表 | ✅ 可删 |
提示：
carrier-config.json是项目可维护性的关键。它把运营商差异抽象成配置项，比如联通接口返回字段是feeBalance，移动是balance，电信是accountBalance——全部由该文件中的fieldMap字段统一映射到前端统一字段balance。改一家运营商接口，只需动这一处。
2.2 接口签名机制：不是加密，是“让服务器相信你刚从它家页面点进来”
运营商接口不校验Token，但校验“你是不是从它家网页发起的请求”。签名逻辑藏在query-balance.js的generateSign()函数里：
function generateSign(phone, timestamp) { const salt = config.salt; // 从carrier-config.json读取 const raw = `${phone}${timestamp}${salt}`; return btoa(raw).substring(0, 16); // 注意：不是MD5，是base64截断！ }这段代码的玄学在于：btoa()生成的base64字符串，取前16位作为sign参数。为什么是16位？因为抓包发现运营商接口实际只校验前16位（后16位无论填什么都通过）。这是典型“历史遗留协议”——当年开发人员随手写的校验，十年没动过。
调用时这样组合：
const ts = Date.now().toString(); const sign = generateSign('13800138000', ts); const url = `${config.apiUrl}?phone=13800138000&ts=${ts}&sign=${sign}`;注意：
ts参数必须是毫秒级时间戳，且与生成sign的时间戳完全一致。差1ms都会返回{"code":401,"msg":"非法请求"}。这是踩坑最多的地方——很多开发者用new Date().getTime()生成时间戳，但没注意fetch发起请求有网络延迟，导致ts和sign时间不一致。
2.3 Cookie注入机制：如何让浏览器自动带上运营商登录态？
这是项目能“免验证码”的核心。它不模拟登录，而是复用用户已有的运营商官网登录态。实现方式分两步：
引导用户先手动登录：
index.html顶部有醒目提示：“请先访问 https://www.10086.cn 并完成登录，再返回本页查询”。这不是客套话，是必要步骤——因为浏览器Cookie是按域名隔离的，www.10086.cn的Cookie不会自动带到你的localhost:8080。强制同域发起请求：所有查询请求的
credentials: 'include'必须开启，且fetch的URL必须是运营商官网域名（如https://www.10086.cn/service/query/balance）。这样浏览器才会自动附带www.10086.cn域下的Cookie。
验证是否生效？打开浏览器开发者工具 → Application → Cookies → 查看www.10086.cn下是否有JSESSIONID和loginToken。没有？说明用户没登录或登录已过期。
提示：某些浏览器（如iOS Safari）默认阻止第三方Cookie。此时需在
index.html中加入<meta name="referrer" content="no-referrer">并提示用户关闭“阻止跨站跟踪”。
3. 运行与调试：三步跑通，但第2步最容易翻车
项目无需构建，解压即用。但“能跑”和“能稳定查”是两回事。下面步骤必须严格按顺序执行，跳过任何一步都可能得到{"code":500,"msg":"系统繁忙"}。
3.1 环境准备：不是Node环境，是浏览器环境
- ✅ 支持：Chrome 80+、Edge 90+、Firefox 78+、Safari 14+
- ❌ 不支持：IE11、微信内置浏览器（禁用
fetch）、QQ浏览器X5内核（拦截跨域Cookie） - ⚠️ 特殊要求：必须启用浏览器的“第三方Cookie”（Chrome设置 → 隐私设置 → Cookie及其他网站数据 → 允许所有Cookie）
提示：开发调试时，务必用
file://协议打开index.html（双击文件），不要用http://localhost:8080启动服务。因为localhost是独立域名，无法共享www.10086.cn的Cookie。生产部署时，需将整个项目部署到与运营商官网同级的子路径下（如https://yourdomain.com/10086-query/），并通过Nginx反向代理隐藏真实域名——但这属于高级用法，新手先用file://模式验证逻辑。
3.2 手动登录：不是“点一下就行”，而是要触发完整会话
很多人卡在这一步：明明在10086官网输完手机号、验证码、点击登录，返回本页还是报错。原因在于——运营商登录是分阶段的：
- 第一阶段：输入手机号，获取短信验证码（此时只生成临时会话）；
- 第二阶段：输入验证码，提交后跳转到首页（此时才写入
JSESSIONID和loginToken）； - 第三阶段：首页自动触发一次
https://www.10086.cn/service/user/info请求（校验登录态，刷新Token有效期）。
必须完成第三阶段。验证方法：在10086官网首页按F12→ Network → 刷一下页面 → 找到user/info请求，状态码必须是200，Response里有"loginStatus":"true"。
血泪经验：某次我在测试联通接口时，反复失败。最后发现是联通官网登录后默认跳转到“我的套餐”页，而该页不触发
user/info请求。解决方案：登录后手动访问https://www.10010.com首页（不是二级路径），再刷一次。
3.3 查询调试：用浏览器Network面板看懂每一个失败
打开index.html→ F12 → Network → 勾选Preserve log→ 输入手机号 → 点击查询。此时你会看到至少3个关键请求：
| 请求URL | 期望状态码 | 关键响应字段 | 失败时看什么 |
|---|---|---|---|
https://www.10086.cn/service/query/balance?... | 200 | {"code":0,"data":{"balance":"86.50"}} | 检查Response Headers里的Set-Cookie是否为空（为空=Cookie失效） |
https://www.10086.cn/service/query/flow?... | 200 | {"code":0,"data":{"remainFlow":"2.3GB"}} | 检查Query String里的sign是否与JS生成的一致（用控制台console.log(sign)对比） |
https://www.10086.cn/service/common/error?code=401 | 401 | {"code":401,"msg":"非法请求"} | 检查Request Headers里的Origin是否为https://www.10086.cn（若为file://则失败） |
提示：如果看到
ERR_CONNECTION_REFUSED，说明运营商封了你的IP——这不是代码问题，是同一IP 1小时内查询超5次触发风控。换WiFi或等10分钟再试。
4. 常见问题排查：5条真实翻车记录，每条都来自生产环境
4.1 现象：点击查询后页面卡住，Network里无任何请求发出
原因：query-balance.js中的fetch被浏览器拦截，控制台报错Blocked a frame with origin "null" from accessing a cross-origin frame。
解决：这是file://协议的安全限制。必须用http-server启动一个本地HTTP服务：
npm install -g http-server http-server -p 8080 # 然后访问 http://localhost:8080注意：http-server默认不带CORS头，但本项目不需要CORS（因为请求发给运营商官网，不是同域），所以直接可用。
4.2 现象：返回{"code":403,"msg":"禁止访问"}
原因：Referer请求头缺失或错误。运营商接口校验Referer必须是其官网完整URL（如https://www.10086.cn/），而file://协议下浏览器不发送Referer。
解决：在query-balance.js的fetch调用前，手动注入Referer：
const headers = new Headers(); headers.set('Referer', 'https://www.10086.cn/'); // ...其他headers fetch(url, { headers, credentials: 'include' });注意：Chrome 95+ 默认禁用手动设置
Referer，需在启动Chrome时加参数：chrome.exe --unsafely-treat-insecure-origin-as-secure="file://"（仅开发用）。
4.3 现象：返回{"code":500,"msg":"系统繁忙"}且持续10分钟以上
原因：运营商接口返回500，通常意味着你触发了风控策略——同一IP在5分钟内查询超3次，或同一手机号1小时内查超2次。
解决：立即停止查询，等待10分钟；或更换网络环境（如切到手机热点）；终极方案：在carrier-config.json中为每个运营商配置多个备用接口URL（抓包可发现移动有/service/query/balanceV2等隐藏路径）。
4.4 现象：余额显示为0.00，但实际有余额
原因：运营商返回的balance字段是字符串"0.00"，但前端JS误判为数字0，导致逻辑分支走错。
解决：在parseResponse()函数中强制类型转换：
const balance = parseFloat(data.balance) || 0.00; // 而不是 if (data.balance) { ... }血泪经验：某次我们上线后收到大量投诉“话费被清零”，查日志发现是
parseFloat("0.00")返回0，而前端判断if (balance)为false，直接显示“余额不足”。
4.5 现象：在Android平板上白屏，控制台报错ReferenceError: fetch is not defined
原因：老旧Android WebView内核（如Android 4.4）不支持fetchAPI。
解决：在index.html中引入whatwg-fetchpolyfill：
<script src="https://cdn.jsdelivr.net/npm/whatwg-fetch@3.6.2/dist/fetch.umd.js"></script>注意：必须放在query-balance.js之前加载，且polyfill版本不能高于3.6.2（高版本依赖Promise，而Android 4.4的Promise也不全）。
5. 二次开发实战：从“能查”到“能管”，加3个功能只需改50行代码
这个项目的价值不在“能查话费”，而在“能嵌入、能管控、能告警”。下面三个改造，我都已在某省电力公司巡检终端上落地，每项增加代码不超过20行，但解决了真实业务痛点。
5.1 功能增强1：自动轮询+余额预警（加18行）
原始项目是手动点击查询。但巡检终端需每30分钟自动查一次，余额低于50元时触发声光报警。改造思路：用setInterval封装查询逻辑，并监听返回值。
// 在 query-balance.js 底部追加 let lastBalance = 0; const CHECK_INTERVAL = 30 * 60 * 1000; // 30分钟 function startAutoCheck() { setInterval(async () => { try { const result = await queryBalance(document.getElementById('phone').value); if (result.balance && result.balance < 50 && lastBalance >= 50) { // 余额跌破50元，触发报警 triggerAlarm(); } lastBalance = result.balance || 0; } catch (e) { console.warn('自动查询失败:', e.message); } }, CHECK_INTERVAL); } function triggerAlarm() { // 播放报警音效（需提前准备alarm.mp3） const audio = new Audio('alarm.mp3'); audio.play(); // 闪烁屏幕（CSS类控制） document.body.classList.add('alarm-pulse'); setTimeout(() => document.body.classList.remove('alarm-pulse'), 2000); }关键细节：
lastBalance用于判断“是否首次跌破阈值”，避免每次查询都报警；triggerAlarm()中的CSS类需在style.css中定义：.alarm-pulse { animation: pulse 0.5s infinite; } @keyframes pulse { 0% { background:#fff; } 50% { background:#ff0000; } }
5.2 功能增强2：多号码批量查询（加22行）
原始项目只支持单号码。但电力公司有200台巡检终端，需统一管理SIM卡余额。改造目标：上传CSV文件（含手机号、设备编号、责任人），一键查询全部号码。
<!-- 在 index.html 的表单中追加 --> <div class="batch-section"> <label>批量查询（CSV格式：手机号,设备编号,责任人）</label> <input type="file" id="csvFile" accept=".csv" /> <button onclick="handleBatchUpload()">开始查询</button> <div id="batchResult"></div> </div>// 在 query-balance.js 中追加 async function handleBatchUpload() { const file = document.getElementById('csvFile').files[0]; const text = await file.text(); const lines = text.split('\n').filter(l => l.trim()); const results = []; for (const line of lines) { const [phone] = line.split(','); try { const res = await queryBalance(phone.trim()); results.push({ phone, balance: res.balance, status: 'success' }); } catch (e) { results.push({ phone, balance: '--', status: 'failed' }); } } // 渲染结果表格 const html = results.map(r => `<tr><td>${r.phone}</td><td>${r.balance}</td><td>${r.status}</td></tr>` ).join(''); document.getElementById('batchResult').innerHTML = `<table><tr><th>号码</th><th>余额</th><th>状态</th></tr>${html}</table>`; }注意：CSV解析用最简方案（
split），不引入PapaParse等库，避免增加体积；失败时不中断后续查询，保证200个号码中1个失败不影响其余199个。
5.3 功能增强3：查询日志本地存储（加10行）
原始项目无审计能力。但电力公司要求“谁在何时查了哪个号码”。改造目标：将每次查询记录存入浏览器localStorage，并提供导出按钮。
// 在 queryBalance() 函数末尾追加 function saveQueryLog(phone, result) { const log = { time: new Date().toISOString(), phone, balance: result.balance, flow: result.flow, expire: result.expire }; const logs = JSON.parse(localStorage.getItem('queryLogs') || '[]'); logs.push(log); localStorage.setItem('queryLogs', JSON.stringify(logs.slice(-100))); // 只存最近100条 } // 在 index.html 中加导出按钮 <button onclick="exportLogs()">导出查询日志</button> function exportLogs() { const logs = JSON.parse(localStorage.getItem('queryLogs') || '[]'); const csv = ['时间,号码,余额,流量,到期日'].concat( logs.map(l => `"${l.time}","${l.phone}","${l.balance}","${l.flow}","${l.expire}"`) ).join('\n'); const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' }); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = `query-log-${new Date().toISOString().slice(0,10)}.csv`; a.click(); }提示：
localStorage容量有限（通常5MB），所以用logs.slice(-100)限制数量；导出CSV时用双引号包裹字段，避免手机号含逗号导致解析错位。
从那以后我每次给客户交付话费查询模块，都强制走一遍这三步增强：自动轮询保时效、批量查询提效率、本地日志留凭证。不是为了炫技，而是因为甲方验收时一定会问：“能自动告警吗？”“能查100个号码吗？”“查记录能导出来吗？”——这三问，就是项目从Demo变成生产系统的分水岭。希望帮到你。
本文还有配套的精品资源，点击获取
