独立开发者笔记非官方教程。文中 Token 均为占位符。先用一句话交代产品避免和别的「webrpc」项目搞混webrpc是面向无公网 IP 场景的跨平台 P2P 通信 SDK用 Token 标识设备登录后建立加密会话再用接近 RPC 的方式收发数据/文件。官网与控制台https://www.webrpc.cn/我前面用 Go 写过连通和 NAS 查询示例。换到 Python 后业务逻辑其实更简单真正耗时间的是ctypes 怎么正确加载 Native SDK。这篇文章不重复「webrpc 是什么、和 frp 怎么选」只记我实际踩过、也最容易卡住别人的 7 个坑。最小心智模型Python 版Python 不走 pip 装一个纯 Python 包而是从 webrpc.cn 下载对应平台动态库.dylib/.so/.dll用ctypes.CDLL加载声明每个 C API 的argtypes/restype登录 →GetReceivePort→ 后台线程连127.0.0.1:port读回调帧需要主动联系对端时再OpenSessionSendData回调帧仍是官网那套大端sessionId(4)type(1)type2 为数据流type1 为文件流。坑 1动态库文件名/架构找错现象OSError: dlopen(./libwebrpc-Mac.dylib, 0x0006): tried: ... image not found或 Linux 上libwebrpc-Linux.so: cannot open shared object file。原因文件没和脚本放一起或相对路径不对arm64 机器却放了 x86_64 的 somacOS 需要DYLD_LIBRARY_PATHLinux 需要LD_LIBRARY_PATH有时当前目录也不够怎么改importplatformfrompathlibimportPathdeflibrary_path()-str:basePath(__file__).resolve().parent systemplatform.system()machineplatform.machine().lower()ifsystemDarwin:returnstr(base/libwebrpc-Mac.dylib)ifsystemWindows:returnstr(base/webrpc-Windows.dll)ifmachinein(aarch64,arm64):returnstr(base/libwebrpc-Linux-arm64.so)returnstr(base/libwebrpc-Linux.so)libctypes.CDLL(library_path())跑之前先ls确认文件真的在不要只抄文档里的./libwebrpc-Mac.dylib字符串。坑 2ctypes 不声明类型返回值全是乱的现象LoginStatus看起来永远奇怪OpenSession得到离谱的大整数程序偶发崩溃。原因ctypes 默认把很多返回值当成c_int。webrpc 句柄是uintptrOpenSession返回uint32不声明会 silently 截断或签扩展。怎么改按官网文档把签名写死GoUintptrctypes.c_size_t lib.WebrpcClient_New.argtypes[c_char_p,c_char_p,c_char_p]lib.WebrpcClient_New.restypeGoUintptr lib.WebrpcClient_LoginStatus.argtypes[GoUintptr]lib.WebrpcClient_LoginStatus.restypec_int lib.WebrpcClient_GetReceivePort.argtypes[GoUintptr]lib.WebrpcClient_GetReceivePort.restypec_int lib.WebrpcClient_OpenSession.argtypes[GoUintptr,c_char_p,c_char_p]lib.WebrpcClient_OpenSession.restypec_uint lib.WebrpcClient_SendData.argtypes[GoUintptr,c_uint,c_char_p,c_int,c_longlong]lib.WebrpcClient_SendData.restypec_int lib.WebrpcClient_Free.argtypes[GoUintptr]lib.WebrpcClient_Free.restypeNone字符串一律传bytesbYOUR_TOKEN不要传普通str在 Py3 里会直接 TypeError这算好事。坑 3LoginStatus 一直为 0现象循环打印Login status: 0永远进不了下一步。排查顺序Token / 密码是否从控制台「我的 Token」复制正确有没有前后空格是否用了对应平台的库尤其 M 系列 Mac / Linux arm64机器能否访问外网登录需要平台侧配合是否把 A/B 两个 Token 填反或拿过期订单的 Token给登录加超时别死循环deadlinetime.time()60whiletime.time()deadline:statuslib.WebrpcClient_LoginStatus(handle)ifstatus!0:breaktime.sleep(2)else:raiseTimeoutError(登录超时检查 Token、平台库和网络)坑 4回调端口写死或连错地址现象ConnectionRefusedError: [Errno 61] Connection refused原因端口是 SDK 运行时分配的必须portlib.WebrpcClient_GetReceivePort(handle)socksocket.create_connection((127.0.0.1,port))不要写死8080也不要去连局域网 IP——回调只在本机回环上。另一个细节先GetReceivePort再开线程去连顺序反了偶尔会踩到「端口还没就绪」。坑 5在回调线程里同步 SendData把读循环堵死现象能收到第一条消息回包之后再也收不到或偶发卡死。原因回调线程的职责是尽快读完一帧。若在同一线程里同步SendData且耗时较长读循环停住后续帧堆积。Go 示例用 goroutine 异步回包Python 同样要丢到线程池或另起线程defreply(handle,session_id:int,payload:bytes)-None:def_send():retlib.WebrpcClient_SendData(handle,session_id,payload,len(payload),3000)print(SendData ret ,ret)threading.Thread(target_send,daemonTrue).start()读循环里只做拆帧 → 把业务丢给别的线程 → 立刻读下一帧。坑 6OpenSession 返回 0却以为「Python API 坏了」现象sidlib.WebrpcClient_OpenSession(handle,bPEER_TOKEN,b)# sid 0常见真相对端进程没登录成功PEER_TOKEN填成了自己的 Token两端网络极严握手失败官网也写明不能保证 100% 成功还没启动回调线程就狂发数据建议先让接收端就绪建议先同机两个进程验证业务再家宽 手机热点跨网测。跨网失败时先看对端是否在线、会话数是否增加再怀疑 ctypes。坑 7进程退出忘记 Free或重复 Free现象反复启停脚本后行为怪异Windows 上偶发占用调试时「上次句柄未释放」。怎么改handlelib.WebrpcClient_New(bYOUR_TOKEN,bYOUR_PASSWORD,b)try:run(handle)finally:ifhandle:lib.WebrpcClient_Free(handle)handle0Free后不要再拿旧句柄SendData。长期驻留的 Agent 用信号SIGINT走同一条清理路径。一份「避坑版」骨架可直接改下面不是完整业务只是把上面 7 个坑对应的写法收拢到一起#!/usr/bin/env python3importctypesimportplatformimportsocketimportstructimportthreadingimporttimefromctypesimportc_char_p,c_int,c_longlong,c_uintfrompathlibimportPath GoUintptrctypes.c_size_tdefload_lib():basePath(__file__).resolve().parent system,machineplatform.system(),platform.machine().lower()ifsystemDarwin:pathbase/libwebrpc-Mac.dylibelifsystemWindows:pathbase/webrpc-Windows.dllelifmachinein(aarch64,arm64):pathbase/libwebrpc-Linux-arm64.soelse:pathbase/libwebrpc-Linux.soifnotpath.exists():raiseFileNotFoundError(path)returnctypes.CDLL(str(path))libload_lib()lib.WebrpcClient_New.argtypes[c_char_p,c_char_p,c_char_p]lib.WebrpcClient_New.restypeGoUintptr lib.WebrpcClient_LoginStatus.argtypes[GoUintptr]lib.WebrpcClient_LoginStatus.restypec_int lib.WebrpcClient_GetReceivePort.argtypes[GoUintptr]lib.WebrpcClient_GetReceivePort.restypec_int lib.WebrpcClient_SendData.argtypes[GoUintptr,c_uint,c_char_p,c_int,c_longlong]lib.WebrpcClient_SendData.restypec_int lib.WebrpcClient_Free.argtypes[GoUintptr]lib.WebrpcClient_Free.restypeNonedefrecv_exact(sock,n):bufbwhilelen(buf)n:chunksock.recv(n-len(buf))ifnotchunk:raiseConnectionError(closed)bufchunkreturnbufdefcallback_loop(handle,port):withsocket.create_connection((127.0.0.1,port))assock:whileTrue:sidstruct.unpack(I,recv_exact(sock,4))[0]typrecv_exact(sock,1)[0]iftyp!2:# 文件帧按文档跳过或另处理continuenstruct.unpack(I,recv_exact(sock,4))[0]datarecv_exact(sock,n)print(recv:,data)payloadbReceivedthreading.Thread(targetlambda:lib.WebrpcClient_SendData(handle,sid,payload,len(payload),3000),daemonTrue,).start()defmain():handlelib.WebrpcClient_New(bYOUR_TOKEN,bYOUR_PASSWORD,b)ifnothandle:raiseSystemExit(New failed)try:deadlinetime.time()60whiletime.time()deadline:iflib.WebrpcClient_LoginStatus(handle)!0:breaktime.sleep(2)else:raiseTimeoutError(login timeout)portlib.WebrpcClient_GetReceivePort(handle)threading.Thread(targetcallback_loop,args(handle,port),daemonTrue).start()print(ready, callback port ,port)whileTrue:time.sleep(3)finally:lib.WebrpcClient_Free(handle)if__name____main__:main()更完整的官方示例在控制台「开发文档 → Python」https://www.webrpc.cn/最后Python 接 webrpc难的通常不是「会不会写 socket」而是动态库与架构ctypes 类型声明登录与回调时序回包不要堵读循环把这四块做稳后面的 JSON 业务、目录查询、文件传输和语言无关。再次提醒webrpc 是无公网 IP 可用的 P2P 通信 SDK详情与套餐以官网为准——https://www.webrpc.cn/。握手并非任何网络下都 100% 成功产品层请保留超时与重试。仅用于合法业务。