简介这是一份基于Java开发的微信wxid转换工具可运行源码面向微信开发入门者及需要处理微信号与二维码映射的Java工程师可完成wxid转二维码、模拟微信号转wxid以及CSV批量转换。压缩包共10个文件包含3个Java核心类、2个XML工程配置、1个二维码示例PNG、1个CSV样例、1个HTML展示页及辅助文件整体仅12KB结构精简便于阅读。工具借助ZXing库生成二维码核心WxidConverter类集中管理转换逻辑适合学习二维码生成、Java工程配置与批量数据处理流程。目前已有1946人学习参考下载后可直接导入IDE运行调试也可基于样例扩展自定义转换场景。 最近在整理微信通讯录数据时遇到一个挺磨人的场景手里有一批联系人的wxid但微信号那一栏是空的。用 wxid 去搜索添加好友微信压根不认想通过微信号做批量建档、去重又拿不到对应数据。折腾了几个晚上我把这个“微信 wxid 转换工具”从需求到可运行源码完整撸了一遍。这篇博文就把当时的实现思路、踩坑点、核心代码全部分享出来适合做微信生态工具开发、通讯录数据清洗、私域运营系统对接的开发者参考。先说明一个边界这个工具处理的是你本人或你已获得授权的通讯录数据比如自己微信的网页版联系人快照、企业微信后台导出的成员清单、或本地聊天记录里提取的对象信息。用它去批量探测陌生人的隐私属于违规操作别碰。1. wxid和微信号先搞清这两个ID的关系1.1 两种ID的生成规则和表现形式微信里的用户标识符分两套体系。第一套是系统内部使用的wxid_开头的唯一 ID用户注册时由微信服务器分配人眼看起来就是一串无规律的字符加数字例如wxid_a1b2c3d4。这套 ID 用户无法自行修改也不会显示在个人资料页的显眼位置平时只有在源码、接口日志、数据库导出、某些扫码数据里才能看到。第二套是用户自定义的微信号比如ming_2024、zhang_san这种形式。它主要用来被搜索和添加好友支持 6-20 位字母、数字、下划线和减号。两者之间的对应关系存在微信服务器上客户端拿到的只是一份“联系人名单”。名单里既写了UserName内部 ID经常就是wxid_格式也写了Alias用户自定义微信号而“转换”这个动作本质上是把名单里这两列做成映射关系。有个容易被忽略的细节wxid_本身也可能出现在微信号输入框里。部分老微信号在用户从未设置过自定义 ID 时会直接把系统分配的wxid_xxx作为微信号展示。这时候两个 ID 看上去一样但语义完全不同。工具能不能区分能但必须看数据来源里的字段归属而不是只看字符串前缀。1.2 为什么这类工具很需要但又不能“直接反查”我在设计工具前先明确了一个事实微信没有任何公开、稳定的接口支持“输入 wxid 得到微信号”这种查询。你在通讯录里能看到的Alias是微信为了“好友之间互相识别”主动下发的数据而不是通过某个三元组反查出来的。某种意义上这和电话本很像你手里有一个人的手机号想看他绑定的微信号除非通讯录里已经存了这条关联记录否则运营商不会提供一个查询接口给你。所以工具的核心不是“破解”或“解密”而是“把分散在多个数据源里的 wxid 与微信号对应关系统一捞出来、建索引、支持批量检索”。想清楚这一点整个软件结构就简单了读数据、清洗字段、建映射表、查表。1.3 使用场景什么时候你会需要它我最开始做这个工具是因为在维护一套客户管理系统。系统里存的是历史对接过程中抓到的wxid但商务同事在企微群里汇报时习惯用微信号来标识客户。两边对不上每周要对半天表格。有了转换工具后我可以把客户表格里的wxid一列批量替换成可读的微信号再和企微导出表做匹配效率提升非常明显。其他常见场景还包括开发者调试微信相关程序时定位测试账号、从备份数据中还原“僵尸好友”的真实身份、运营人员把扫码进群用户的原始 ID 转成可备注的微信号再打标签。这类需求往往一次只需要处理几百到几千条数据不需要重型系统一个命令行工具加一个静态索引文件就足够。2. 转换工具的整体设计数据源决定转换结果2.1 首选数据源网页微信联系人快照“转换”要成立必须拿到同时包含wxid和Alias的原始数据。在微信网页版的联系人同步接口里一次webwxgetcontact请求会返回一份 JSONMemberList数组中的每个成员包含多个字段{ MemberList: [ { UserName: wxid_a1b2c3d4, NickName: 小明, RemarkName: 客户-王小明, Alias: wxid_a1b2c3d4, Sex: 1 }, { UserName: wxid_xyz5678, NickName: Tech, RemarkName: , Alias: tech_2024, Sex: 0 } ] }注意第一组数据Alias和UserName一样说明这位用户从未设置过自定义微信号第二组数据才是真正有转换价值的目标。我把网页版登录后拿到的MemberList整体保存成contacts.json然后作为工具的输入。这样处理最简单因为代码里不需要模拟登录、不需要维护会话只做纯离线解析。2.2 备选数据源本地导出清单和企微 CSV有些场景下网页微信登录受限比如微信会检测新设备或异常风险而拒绝登录网页版。这时候可以退而求其次从企微后台导出通讯录 CSV。企微联系人通常会有wxid对应的账号 ID以及用户的对外微信号字段不过字段名不一定叫Alias可能是wechat_id、external_userid之类需要先看一眼表头再映射。还有一些运营同学会从旧手机备份、聊天记录数据库里提取出联系人对象里面同样会有UserName和Alias。只要字段能对上格式是 JSON 还是 CSV 对工具来说没有本质差别。我后来甚至为了应急把微信 Mac 旧版本聊天记录数据库里导出的message表做了一层解析通过群成员字段同时捞到了 wxid 和微信号也塞进了同一个映射表。2.3 映射表结构设计不管数据来源有多少种最终都会归一成一张简单的表。我用了两个核心字段作为键原始wxid和标准化后的alias再加上nickname、remark是为了后续排查方便字段名类型说明wxidstring原始 UserName通常是wxid_开头aliasstring用户自定义微信号为空表示没设置过nicknamestring昵称用于人工比对remarkstring备注名用于人工比对sourcestring数据来源标记比如webwx、csv存储结构用 Python 的dict就够了key 是 wxidvalue 是包含上述字段的对象。因为现实里目标数据量级也就是几千到几万条内存完全吃得下不需要上 Redis 或者数据库。如果以后数据量到几十万条再考虑用 SQLite 或者落盘索引也不迟。3. 源码实现一个能直接跑起来的转换工具3.1 核心类 WxidConverter 实现我先把核心逻辑封装成一个类它只负责三件事加载数据、建索引、执行转换。这样既能被命令行调用也能被后续的 HTTP 服务复用。import json import csv import argparse class WxidConverter: def __init__(self): self.records {} def load_json(self, path): 加载网页微信联系人 JSON 快照 with open(path, r, encodingutf-8) as f: data json.load(f) member_list data.get(MemberList, data if isinstance(data, list) else []) for item in member_list: uid item.get(UserName) or item.get(wxid) if not uid: continue self.records[uid] { wxid: uid, alias: item.get(Alias, ) or , nickname: item.get(NickName, ) or item.get(nickname, ) or , remark: item.get(RemarkName, ) or item.get(remark, ) or , source: json } def load_csv(self, path): 加载通用联系人 CSV字段名支持常见别名 with open(path, r, encodingutf-8-sig) as f: reader csv.DictReader(f) for row in reader: uid row.get(wxid) or row.get(UserName) or row.get(账号ID) if not uid: continue self.records[uid] { wxid: uid, alias: row.get(alias) or row.get(微信号) or row.get(wechat_id) or , nickname: row.get(nickname) or row.get(昵称) or , remark: row.get(remark) or row.get(备注) or , source: row.get(source) or csv } def get_wechat_id(self, wxid): 输入 wxid返回微信号没有则返回 None rec self.records.get(wxid) if not rec: return None return rec[alias] if rec[alias] else None def convert_batch(self, wxid_list): 批量转换返回 wxid - 微信号 的字典 result {} for wxid in wxid_list: result[wxid] self.get_wechat_id(wxid) return result def search_by_alias(self, alias): 反向查询输入微信号返回所有匹配的 wxid 列表 return [rec for rec in self.records.values() if rec[alias] alias] def export_mapping(self, output_path): 导出完整映射表为 CSV方便后续手工核对 with open(output_path, w, encodingutf-8-sig, newline) as f: writer csv.DictWriter(f, fieldnames[wxid, alias, nickname, remark, source]) writer.writeheader() for rec in self.records.values(): writer.writerow(rec) def summary(self): 返回统计信息总条数、有微信号条数、无微信号条数 total len(self.records) has_alias sum(1 for rec in self.records.values() if rec[alias]) return total, has_alias这段代码有几点值得说明。第一load_csv里写了不少字段别名因为不同导出工具的列名五花八门有的叫微信号有的叫wechat_id有的干脆叫alias。多写几个or能省掉大量手工预处理。第二get_wechat_id返回空字符串或None的语义区分很重要空字符串表示“该联系人确实没设置微信号”None表示“名单里根本没这个人”这两者在排查数据问题时含义完全不同。3.2 命令行入口单查、批查、反查光有核心类还不够我用argparse写了一个命令行人机交互层支持三种查询方式单条查询、批量查询、反查微信号。这样实际使用时不用改代码直接在终端输命令就能跑。def main(): parser argparse.ArgumentParser(description微信 wxid 转换工具) parser.add_argument(--load-json, typestr, help加载网页微信联系人 JSON 文件) parser.add_argument(--load-csv, typestr, help加载联系人 CSV 文件) parser.add_argument(--query, typestr, help查询单个 wxid 对应的微信号) parser.add_argument(--batch, typestr, help批量查询传入文本文件每行一个 wxid) parser.add_argument(--search-alias, typestr, help反向查询微信号对应的 wxid) parser.add_argument(--export, typestr, help导出完整映射表为 CSV 文件) parser.add_argument(--stats, actionstore_true, help输出统计信息) args parser.parse_args() converter WxidConverter() if args.load_json: converter.load_json(args.load_json) if args.load_csv: converter.load_csv(args.load_csv) if not converter.records: print(没有加载到任何数据请检查输入文件路径。) return if args.query: result converter.get_wechat_id(args.query) print(json.dumps({wxid: args.query, wechat_id: result}, ensure_asciiFalse, indent2)) if args.batch: with open(args.batch, r, encodingutf-8) as f: wxid_list [line.strip() for line in f if line.strip()] result_map converter.convert_batch(wxid_list) for wxid, wechat_id in result_map.items(): print(f{wxid}\t{wechat_id or (未设置微信号)}) if args.search_alias: matches converter.search_by_alias(args.search_alias) print(json.dumps(matches, ensure_asciiFalse, indent2)) if args.export: converter.export_mapping(args.export) print(f已导出至 {args.export}) if args.stats: total, has_alias converter.summary() print(f总联系人: {total}, 有微信号: {has_alias}, 无微信号: {total - has_alias}) if __name__ __main__: main()实际使用示例python wxid_converter.py --load-json contacts.json --query wxid_a1b2c3d4 python wxid_converter.py --load-json contacts.json --batch wxid_list.txt python wxid_converter.py --load-json contacts.json --search-alias tech_2024 python wxid_converter.py --load-json contacts.json --export mapping.csv --stats命令行工具最大的好处是可重复执行。我可以把contacts.json每周导出一份然后跑一遍批查生成最新的映射表再接上后续的清洗流程整个过程不用打开任何图形界面。这里有个细节批量查询文件里每行一个 wxid但有些 wxid 会带多余空格或者前缀。脚本里用strip()做了弱清洗但遇到前缀的 ID 需要另外处理。我自己在脚本里加了一段逻辑只有字段是wxid_开头时才做转换否则跳过避免把群聊 ID 或特殊账号混进来。3.3 封装成 HTTP 接口给同事用的可选方案命令行工具自己用没问题但同事不需要碰终端。我后来给这个工具套了一层薄薄的 Flask 接口让前端能够通过GET请求直接查询。核心代码很简洁from flask import Flask, request, jsonify app Flask(__name__) converter WxidConverter() converter.load_json(contacts.json) app.route(/convert, methods[GET]) def convert(): wxid request.args.get(wxid) if not wxid: return jsonify({error: missing wxid}), 400 wechat_id converter.get_wechat_id(wxid) if wechat_id is None: return jsonify({error: wxid not found}), 404 return jsonify({wxid: wxid, wechat_id: wechat_id}) app.route(/batch_convert, methods[POST]) def batch_convert(): payload request.get_json(forceTrue) wxid_list payload.get(wxids, []) result converter.convert_batch(wxid_list) return jsonify(result) if __name__ __main__: app.run(host0.0.0.0, port5000, debugFalse)接口虽然简单但解决了一个现实痛点。我把服务跑在一台内网测试机上同事只需要在浏览器里访问http://192.168.x.x:5000/convert?wxidwxid_a1b2c3d4就能拿到微信号。如果不希望暴露服务端口也可以继续用命令行工具两条路互不干扰。4. 实站中的避坑经验4.1 网页微信联系人接口不稳定的替代方案网页微信登录和联系人同步接口目前对部分账号已经不可用尤其是一些注册时间比较晚的微信号登录网页版时会直接提示“当前环境异常请使用手机微信扫码”但扫码后依然无法进入。我遇到这种情况后第一反应不是去模拟更复杂的协议而是换了数据源。最靠谱的替代方案是走企业微信后台。企业微信成员列表导出成 CSV 后里面经常直接包含wxid和企微对外微信号字段虽然在表格里分布得比较隐蔽但清洗一次后就能和核心类对上。其次是旧版 Windows/Mac 微信的本地数据库里面保存的联系人对象同样包含UserName和Alias不过这需要额外写一段数据库解析逻辑不是纯 Python 脚本能直接搞定的。我建议在工具设计之初就留好source字段。这样即使不同来源的数据对同一个 wxid 产生了不同 alias比如用户修改过微信号也能通过 source 和时间戳决定采信哪条避免数据冲突。4.2 Alias 为空或已经修改过微信号的情况转换结果里最常出现的意外是明明加载了几千人统计时却发现有微信号的只有一半。剩下那一半的Alias字段是空的这时工具返回(未设置微信号)而不是报错。这个语义在设计上是对的但实际操作中还要再往下追一层这位用户是不是真的从没设置过微信号根据我的经验有几种情况会导致 alias 缺失一是老微信号注册时被分配了一个wxid_开头的默认 ID用户一直没改二是用户曾经设置过微信号但后来改了旧 DB 里Alias没更新三是数据源的字段名根本不是Alias而是EncryptUserName这种加密字段代码没识别到。遇到第二种情况最有效的办法是更新数据源。如果是网页微信快照重新登录一次再拉一遍联系人列表如果是 CSV找一个较新的导出版本覆盖。已经修改过微信号的联系人旧映射表里的结果已经失效这种情况下“转换”本身没有意义只能靠实时接口或人工确认不可强求。4.3 编码、去重与异常 ID 清理中文昵称和备注在 JSON、CSV 之间倒腾时最大的坑是编码。命令行工具里我统一使用utf-8读文件导出 CSV 时使用utf-8-sig这样 Excel 打开才不会是乱码。如果数据源是从 Windows 老系统导出的gbk编码直接交给代码解析会出现UnicodeDecodeError需要先用编辑器转成 UTF-8。清理逻辑我也踩过坑。联系人列表里偶尔会出现一些特殊账号比如gh_开头的公众号、开头的群聊临时账号、wxid_前缀但后面跟着中文的异常 ID。我在load_json里补了一个简单的判断只有UserName匹配^wxid_模式的才进入索引公众号、企业号不参与转换因为这些对象的微信号概念和普通用户不同混进去只会污染结果集。另一个容易被忽略的小点是去重。企微 CSV 和网页微信 JSON 如果同时加载同一个 wxid 可能会出现两次。我的处理策略是后加载的覆盖先加载的但保留 source 字段供追溯。你也可以改成“先到先得”关键看数据源优先级。我更推荐后者因为网页微信联系人快照的信息通常比 CSV 更准确。这部分逻辑可以根据自己团队的数据情况微调核心是让结果可追溯而不是拍脑袋决定覆盖方向。5. 最后补充一点实际心得工具做到能跑只是在第一步真正让它产生价值的是你愿意花时间把数据源维护好。我后来养成了一个习惯每次登录网页版微信后都会手动拉一次联系人快照存成带日期的文件比如contacts_20250115.json。这样即使微信某天调整了协议我手里也还有一整套历史数据可以重放工具不会猝死。另一个建议是如果你接手了这类转换需求先问清楚对方要的是“实时查询”还是“批量归档”。前者需要稳定的接口和在线会话工程复杂度高后者只需要离线快照加命令行工具整体能控制在两百行代码以内。很多需求实际上根本不需要实时你要做的是帮对方把期望引导到合理的方案上。这款工具到现在依然稳定跑在我本地的定时任务里每周更新一次映射表配合企业微信后台的清洗流程已经成为了我通讯录管理流程里最不起眼但最可靠的一环。本文还有配套的精品资源点击获取