简介：Jpcap 使用文档与 jpcap.jar 面向希望在 Java 环境中开展网络数据包捕获、协议解析与网络安全实验的开发者，尤其适合需要快速上手 Jpcap API 的初学者，以及进行网络监控、流量分析的中级读者。压缩包共 112 个文件，约 351KB，主体为 106 个 HTML 格式的 API 文档页面，辅以 2 个 jar 库文件、样式表、索引与清单文件，便于离线查阅类库说明、定位抓包与发包接口。已有 693 人学习，说明其在 Java 抓包入门场景中具有一定参考价值。文档围绕 JpcapCaptor、JpcapSender、Packet 等核心类展开，覆盖安装配置、BPF 过滤规则、网卡识别、数据包捕获解析与自定义发送等主题，并配有示例与调试思路；配合 jpcap.jar 可直接引入项目类路径，帮助读者理解从抓包到分析的完整流程，减少环境配置和 API 检索成本。
1. 先跑通再说：jpcap.jar 不是丢进 lib 就能抓包的库
很多 Java 工程师第一次拿到 jpcap.jar，习惯性把它丢进工程的 lib 目录，写一行JpcapCaptor.getDeviceList()，然后被一记UnsatisfiedLinkError: no jpcap in java.library.path打回原形。这个包的本质从来不是纯 Java 库，它是 Java 对 libpcap / WinPcap 这层系统抓包驱动做的 JNI 封装，jar 里只有 Java 侧的类，真正干活的是一份本地动态库。这份「jpcap 使用文档 + jpcap.jar」的组合，价值就在于把两半拼齐：文档负责讲清每个类怎么用、每个字段什么含义，jar 负责提供编译期的类型定义。它适合三类人：需要在 Java 工程里做协议分析、做教学演示工具、接手了一套老系统要补抓包能力的人。如果你指望它像 Netty 那样开箱即用，或者要在 ARM 服务器上跑高吞吐采集，那它不合适，先接受这个定位再往下看。
2. 环境落地：JDK、原生库与 jpcap.jar 的三件套配齐
jpcap 的环境问题，九成出在「以为只装了一个东西」。把它的依赖关系拆开看，从上到下是三层，任何一层缺位都会表现为同一个症状：程序启动即崩，而且报错信息往往指向不到真正的根因。
2.1 分层理解：Java 壳、JNI 桥、系统抓包驱动
第一层是 jpcap.jar，里面是jpcap.JpcapCaptor、jpcap.Packet、jpcap.TCPPacket这些类的字节码，它只提供接口签名和少量的 Java 侧解析逻辑。第二层是 JNI 桥接库，Windows 下叫jpcap.dll，Linux 下叫libjpcap.so，由 Java 在第一次触碰 native 方法时通过System.loadLibrary("jpcap")加载。第三层是系统驱动，Windows 是 WinPcap（或兼容模式的 Npcap），Linux 是 libpcap，macOS 走的是 BSD 的 bpf 设备。三层的关系和缺失时的表现，我整理成了一张表，排查时照着对：
| 组件 | 文件形态 | 负责什么 | 缺失时的典型症状 |
|---|---|---|---|
| jpcap.jar | jar 包 | 类定义、协议字段封装 | 编译期直接报找不到符号 |
| jpcap 原生库 | jpcap.dll / libjpcap.so | JNI 方法实现 | UnsatisfiedLinkError: no jpcap in java.library.path |
| 系统抓包驱动 | WinPcap / libpcap | 网卡枚举与内核态拷贝 | JpcapCaptor.openDevice抛 IOException 或返回空设备列表 |
| 权限 | 无（root / 管理员） | 打开混杂模式、读原始帧 | Linux 下Permission denied，Windows 下设备列表为空 |
这张表我建议贴在工程 README 里，因为它能省掉大量「重装 JDK 试试」的无效尝试。有个反直觉的点：UnsatisfiedLinkError很多时候不是路径没配，而是位数不匹配——64 位 JDK 加载了 32 位 dll，Windows 给出的报错和「找不到文件」几乎一模一样，属于典型的黑匣子。
2.2 三步把工程跑起来
第一步，把 jar 固定到工程里并建立可复现的目录结构。我不建议直接依赖 IDE 的「Add External JARs」，换台机器就丢配置。用最朴素的方式：
# 工程根目录结构（手工维护，不依赖任何构建工具也能编译） # jpcap-demo/ # lib/jpcap.jar # native/jpcap.dll <- Windows 64 位 # native/libjpcap.so <- Linux # src/ListDevices.java # out/ cd jpcap-demo javac -encoding UTF-8 -cp "lib/jpcap.jar" -d out src/ListDevices.java-cp指向 jar 是编译期的事，-encoding UTF-8别省，jpcap 的源码注释和部分字符串常量按平台默认编码读会出乱码。第二步，把原生库放到能被子进程找到的位置，或者显式指定：
# Windows：把 native 目录加进 java.library.path java -Djava.library.path=./native -cp "lib/jpcap.jar;out" ListDevices # Linux：注意分隔符是冒号，且需要 root 或 CAP_NET_RAW sudo java -Djava.library.path=./native -cp "lib/jpcap.jar:out" ListDevices-Djava.library.path是给System.loadLibrary("jpcap")用的查找路径，它和-cp是两条完全独立的搜索链，这是最常见的混淆点。第三步，如果你要把程序打成可执行 jar 分发，原生库不能塞进 jar 里指望它自动解压——常见做法是启动脚本里固定-Djava.library.path，或者启动时把 so/dll 从 jar 里释放到临时目录再System.load(绝对路径)，后者要处理临时文件清理，稍麻烦但分发友好。
提示：Linux 上给程序 CAP_NET_RAW 权限比直接 su 更稳妥，
setcap cap_net_raw,cap_net_admin=eip /path/to/java之后普通用户也能打开抓包句柄，但这条命令对 java 可执行文件的全局生效，改之前想清楚。
2.3 网卡枚举：第一段验证环境的代码
设备列表能打出来，说明三层都通了，后面所有问题都变成业务问题而不是环境问题。这段代码是全篇最值得先抄的：
import jpcap.JpcapCaptor; import jpcap.NetworkInterface; import jpcap.NetworkInterfaceAddress; public class ListDevices { public static void main(String[] args) { // 静态方法，内部触发 native 初始化；环境不对就在这里崩 NetworkInterface[] devices = JpcapCaptor.getDeviceList(); if (devices == null || devices.length == 0) { System.out.println("设备列表为空：驱动未安装或权限不足"); return; } for (int i = 0; i < devices.length; i++) { NetworkInterface d = devices[i]; System.out.println("[" + i + "] " + d.name + " | " + d.description); System.out.println(" datalink_type = " + d.datalink_type + " mac = " + macToString(d.mac_address)); for (NetworkInterfaceAddress a : d.addresses) { System.out.println(" addr = " + a.address + " mask = " + a.subnet + " bcast = " + a.broadcast); } } } // jpcap 返回的 mac 是 byte[]，长度不足 6 时要补零，否则拼接会越界 static String macToString(byte[] mac) { if (mac == null || mac.length == 0) { return "unknown"; } StringBuilder sb = new StringBuilder(); for (int i = 0; i < mac.length; i++) { if (i > 0) sb.append(':'); sb.append(String.format("%02x", mac[i] & 0xff)); } return sb.toString(); } }这段代码有两个参数需要解释。d.name在 Windows 下是\Device\NPF_{一串 GUID}这种形式，人和程序都不好认，所以选网卡时正确姿势是匹配description里的可读名称（比如网卡型号名），而不是硬编码 GUID——换机器 GUID 必变，属于血泪经验。d.datalink_type是链路层类型，以太网是NetworkInterface.DLT_EN10MB，抓无线管理和 radiotap 头的时候这个值不一样，解析代码里要先判断再强转，否则会拿到一帧谁都不认识的字节流。addresses可能为空数组，遍历前不必判空但循环体里要防null的 broadcast。
3. 抓包主循环：从 openDevice 到 TCPPacket 的解析链路
环境通了以后，重点就变成「怎么把字节流变成你能用的字段」。jpcap 的解析模型是典型的分层强转：拿到的永远是Packet基类，然后按链路层、网络层、传输层一层层instanceof往下走。理解这个模型，比记住任何 API 都重要。
3.1 openDevice 的四个参数怎么定
签名是JpcapCaptor.openDevice(NetworkInterface device, int snaplen, boolean promisc, int toMs)。四个参数各有说法，我的取值建议放在下面：
| 参数 | 含义 | 常用取值 | 取错的表现 |
|---|---|---|---|
| device | 从设备列表里选中的网卡 | 按 description 匹配 | 打开成功但一包不抓 |
| snaplen | 单包最大截取字节数 | 65535 或 1500+14 | 大包被截断，TCP payload 不完整 |
| promisc | 是否混杂模式 | 本机调试 true，长期运行 false | 交换机环境下抓不到他人流量（正常） |
| toMs | 读超时毫秒 | 50～200 | 设为 0 时getPacket可能永久阻塞 |
snaplen是最容易被低估的参数。设成 96 这种小值，你看到的是完整的以太头加 IP 头，但 HTTP 报文体全部丢失，解析出来的 payload 长度永远对不上，新手会怀疑是解析逻辑写错了。设成 65535 更保险，代价是内存占用，长时间高速抓包时配合环形缓冲使用比较稳。toMs直接影响getPacket()的返回行为：超时后返回null，这是正常现象不是错误，循环里必须判空，否则 NullPointerException 会淹没真正的信号。
3.2 PacketReceiver 与向下转型的正确次序
processPacket(int count, PacketReceiver handler)是推模式，count传 -1 表示一直抓，传正数表示收够就返回。回调里做解析，注意强转顺序必须自外向内：
import jpcap.*; import jpcap.packet.*; JpcapCaptor captor = JpcapCaptor.openDevice(dev, 65535, true, 100); captor.processPacket(-1, new PacketReceiver() { @Override public void receivePacket(Packet packet) { // 1) 链路层：以太帧，拿到 MAC 和上层协议类型 if (!(packet instanceof EthernetPacket)) { return; } EthernetPacket eth = (EthernetPacket) packet; // 2) 网络层：只有 IPv4 才有 IPPacket，ARP 是单独的类型 if (!(eth.data instanceof IPPacket)) { return; } IPPacket ip = (IPPacket) eth.data; if (ip.protocol != IPPacket.IPPROTO_TCP) { return; } // 3) 传输层：这里才拿得到端口和 TCP 标志位 TCPPacket tcp = (TCPPacket) ip.data; String flags = (tcp.syn ? "S" : "") + (tcp.ack ? "A" : "") + (tcp.fin ? "F" : "") + (tcp.rst ? "R" : ""); System.out.printf("%s:%d -> %s:%d len=%d flags=%s seq=%d%n", ip.src_ip.getHostAddress(), tcp.src_port, ip.dst_ip.getHostAddress(), tcp.dst_port, tcp.data == null ? 0 : tcp.data.length, flags, tcp.sequence); } });几个细节值得停一下。eth.data不一定就是IPPacket，ARP 帧下面挂的是ARPPacket，VLAN 环境下还可能多一层标签，直接(IPPacket) eth.data会抛 ClassCastException，所以instanceof不是可选的装饰。TCPPacket.data是byte[]，空载荷的纯 ACK 包这里是null而不是长度 0 的数组，取值前必须判空。ip.src_ip是InetAddress类型，要字符串就getHostAddress()，别直接toString()，后者会带一个斜杠前缀，写日志时很难看。tcp.sequence和tcp.ack_num是 long，用来做流重组和 RTT 统计的起点。
3.3 落盘成 pcap：最小可复现闭环
现场抓不到问题的时候，最有效的办法是先落盘再用通用工具看，而不是在 Java 代码里加一万行打印。jpcap 自带JpcapWriter，写出来的就是标准 pcap 格式：
import jpcap.*; import jpcap.packet.*; import java.io.IOException; public class DumpToPcap { public static void main(String[] args) throws IOException { NetworkInterface dev = JpcapCaptor.getDeviceList()[0]; JpcapCaptor captor = JpcapCaptor.openDevice(dev, 65535, true, 100); // 关键：过滤器必须在开始抓包之前设置，否则对已排队的包不生效 captor.setFilter("tcp port 80 or tcp port 443", true); JpcapWriter writer = JpcapWriter.openDump(dev, "session.pcap"); long deadline = System.currentTimeMillis() + 30_000L; while (System.currentTimeMillis() < deadline) { Packet p = captor.getPacket(); // 超时返回 null，用 continue 兜住 if (p == null) continue; writer.writePacket(p); } writer.close(); captor.close(); } }setFilter的第二个参数optimize交给 BPF 编译器做优化，一般传true。getPacket()是拉模式，和processPacket的推模式二选一，不要在同一次抓包里混用，混用后你会看到一个线程拿包另一个线程永远超时。writer.close()必须执行，否则 pcap 文件头没写完，用通用工具打开会提示文件损坏——这个坑我踩过一次，排查了半小时才发现是进程被 kill 导致的。
4. BPF 过滤器与发包：语法边界和字段填充
抓到包只是第一步，能不能只抓你要的包、能不能主动发出一个包，是 jpcap 真正的分水岭。这两件事分别对应 BPF 过滤器和JpcapSender，前者坑在静默失效，后者坑在字段填不全导致包被对端丢弃。
4.1 setFilter 的时机与 BPF 表达式写法
BPF 语法本身是一套独立的小语言，jpcap 只是把它转发给底层驱动编译。常用表达式如下：
| 目标 | 表达式 | 备注 |
|---|---|---|
| 指定主机 | host 192.168.1.20 | 双向都命中 |
| 指定端口 | tcp port 8080 | 不含 UDP |
| 组合条件 | tcp port 80 and host 192.168.1.20 | 与或非用 and / or / not |
| 排除某段 | not net 192.168.0.0/16 | 网段写法要带掩码 |
| 只看 SYN | tcp[tcpflags] & tcp-syn != 0 | 按 TCP 头偏移取值 |
JpcapCaptor captor = JpcapCaptor.openDevice(dev, 65535, true, 100); // 先设过滤器，越早越好；语法错误会在这里抛 IOException captor.setFilter("tcp port 8080 and dst host 192.168.1.20", true);关于时机，有一个必须讲清楚的点：setFilter在processPacket/getPacket之前调用才有效，但如果你的程序是「先抓一会儿再改条件」，正确做法是调用后不影响已进入内核缓冲区的包，过滤条件对新包生效。想彻底干净地换条件，稳妥做法是关闭 captor 重新 openDevice，代价是丢几百毫秒的流量，换来逻辑上没有模糊地带。语法错误抛的是IOException，报错信息里会有具体的 token 位置，不要一律 catch 掉打日志，那等于把过滤器变成玄学。
4.2 用 JpcapSender 构造一个 TCP 握手包
发包的难点不在 API，在于三层头必须逐层填对，任何一层字段荒谬，包发出去也是废包。以构造一个 SYN 为例：
import jpcap.*; import jpcap.packet.*; import java.net.InetAddress; public class SendSyn { public static void main(String[] args) throws Exception { NetworkInterface dev = JpcapCaptor.getDeviceList()[0]; JpcapSender sender = JpcapSender.openDevice(dev); InetAddress srcIp = InetAddress.getByName("192.168.1.10"); InetAddress dstIp = InetAddress.getByName("192.168.1.20"); // 传输层：源端口、目的端口、序号、确认号、六个标志位、窗口、紧急指针 TCPPacket tcp = new TCPPacket(40000, 8080, 1000L, 0L, false, false, false, false, true, false, 8192, 0); tcp.data = new byte[0]; // 网络层：版本 4、TTL 64、协议号 TCP(6)、源目 IP IPPacket ip = new IPPacket(4, false, false, false, false, false, 0, 64, IPPacket.IPPROTO_TCP, srcIp, dstIp); ip.data = tcp; // 链路层：目的 MAC 必须是下一跳的，不能乱填；0x0800 表示 IPv4 EthernetPacket eth = new EthernetPacket(dev.mac_address, new byte[]{(byte) 0xaa, (byte) 0xbb, (byte) 0xcc, (byte) 0xdd, (byte) 0xee, (byte) 0xff}, (short) 0x0800); eth.data = ip; sender.sendPacket(eth); sender.close(); } }参数含义逐个说：TCPPacket构造里的窗口 8192 是随意给的，真实环境按对端 MSS 协商，填 0 会被某些协议栈直接丢；sequence用 1000 只是为了可辨识，真实握手要随机化。IPPacket的offset是分片偏移，非分片填 0；protocol用常量而不是硬编码数字 6，可读性好很多。最容易翻车的是EthernetPacket的目的 MAC——填广播地址在局域网能被 ARP 之外的设备看到但不会被正常转发，填错了网关的 MAC 则包直接消失在交换机里，症状是「发送返回成功但对方没收到」，这类问题只能靠对比 tcpdump 输出定位。
4.3 线程模型：抓包为什么必须脱离主线程
processPacket(-1, handler)是阻塞调用，放在主线程里界面立刻假死，命令行里 Ctrl+C 都不好使。常见做法是单开一个采集线程，回调里只做最轻的活：把Packet拷出关键字段到一个有界队列，解析和写盘交给消费线程。队列一定要有界，无界队列在流量突增时会吃光堆内存，然后 OOM 在一个你完全想不到的位置。另一个细节是关闭顺序：先让采集线程跳出循环，再captor.close()，最后关队列，反过来会出现正在getPacket的线程拿到已释放的句柄，报一个没有意义的 native 崩溃。
5. 避坑与排查：jpcap 的五类翻车现场
这一章按「现象 → 原因 → 解决」写，全是我在实际工程里遇到过的，按发生频率排序。
5.1 加载期与环境类问题
坑一：UnsatisfiedLinkError: no jpcap in java.library.path现象是程序一行没跑就崩，报错里连类名都没有。原因有两个：java.library.path没包含 so/dll 所在目录，或者位数不匹配——64 位 JVM 加载 32 位 dll。解决方式是先java -XshowSettings:properties -version 2>&1 | grep library.path确认路径生效，再用file jpcap.dll（Linux）或查看文件属性（Windows）确认位数与 JVM 一致。位数问题最坑的地方在于报错文本和「文件不存在」完全相同。
坑二：设备列表非空但openDevice抛 IOException现象是getDeviceList()正常返回，选中某块网卡后打开失败。原因是所选网卡没有绑定 IPv4 地址，或该网卡是虚拟网卡（虚拟机桥接、容器网卡），底层驱动不允许混杂模式。解决办法是遍历设备时只挑addresses非空且address是 IPv4 的网卡，容器里抓包通常需要把容器网卡显式映射出来，或者干脆换到宿主机上抓。
坑三：Linux 下Permission denied现象是普通用户跑，设备和驱动都正常，打开时被拒。原因是抓包需要读原始套接字权限。解决办法是临时sudo，长期方案是setcap cap_net_raw,cap_net_admin=eip，或者把用户加进有相应权限的组。注意给 java 可执行文件设 cap 会影响机器上所有 Java 程序，评估完再动。
5.2 运行期与解析类问题
坑四：过滤器设了但抓到的包全都不匹配现象是setFilter("tcp port 8080")之后，回调里打印出来的端口有 53、有 22。原因通常是过滤器写在getPacket循环之后，或者写在一个已经被其他线程占用的 captor 上。解决方式是 openDevice 之后立刻 setFilter，中间不插入任何抓包调用；如果确实需要动态换条件，重建 captor 最稳。
坑五：getPacket()频繁返回 null 被当成故障现象是循环里 null 判断打了一堆日志，以为抓不到包。原因是toMs超时是设计行为，空闲网络上 100ms 内没有匹配包就返回 null 是正常的。解决办法是把 null 当作心跳处理，continue即可，同时用计数器统计「连续返回 null 的次数」来判断是网络真空闲还是过滤器把包全过滤掉了——连续几十次 null 就值得停下来检查表达式。
坑六：大包 payload 对不上长度现象是 HTTP 响应体解析出来只有前几十字节，或者Content-Length和实际长度不符。原因是snaplen设小了，超过部分在内核态就被截断。解决办法是 openDevice 时把 snaplen 提到 65535，并接受相应内存开销。这个坑的隐蔽之处在于 TCP 头是完整的，只有应用层数据缺失，看起来像解析 bug 而不是采集配置问题。
6. 进阶：用一次本地回环验证整条链路
把所有零件装起来之后，我最推荐的验证方式不是去抓真实业务流量，而是在本机做一次完全可控的闭环：起一个本地 HTTP 服务，用 jpcap 抓回环网卡，然后拿抓到的 TCP 序号做一次 RTT 计算。这个动作能同时验证设备选择、过滤表达式、协议强转、字段取值四件事，任何一环写错都会立刻暴露，而且不依赖外部网络。
具体做法是：先用JpcapCaptor.getDeviceList()找到回环设备（Windows 下是\Device\NPF_Loopback，Linux 下是lo，注意回环的链路层类型不一定是以太网，datalink_type要先判断），过滤器写tcp port 18080，然后发一个 HTTP 请求触发三次握手。抓到的包按src_port/dst_port分组，用下面这张表核对每个阶段该看到什么：
| 阶段 | 抓到的包特征 | 应验证的字段 |
|---|---|---|
| 握手 | SYN、SYN+ACK、ACK 三个包 | syn/ack标志位、sequence与ack_num的对应关系 |
| 请求 | 客户端端口发往服务端，payload 以GET开头 | tcp.data编码、snaplen是否截断 |
| 响应 | 反向端口，payload 含状态行 | ip.src_ip方向是否正确 |
| 挥手 | FIN 或 RST | fin/rst标志位互斥性 |
RTT 的算法很简单：记录 SYN 的发出时间戳，再记录 SYN+ACK 的到达时间戳，差值就是一次往返。如果用processPacket推模式，时间戳要自己在回调第一行取System.nanoTime()，别在解析完之后取，解析耗时会让 RTT 系统性偏大。如果三次握手一个包都没抓到，先别改代码，把过滤器清空再跑一遍——清空后能抓到，说明问题在 BPF 表达式；仍然抓不到，问题在设备选择或权限。
我做这类验证有个固定习惯：每次换机器、换 JDK、换操作系统，都先跑一遍这个回环用例，通过了再碰真实流量。因为 jpcap 这种带 JNI 的老库，环境差异造成的问题远比代码问题多，而回环用例是唯一能在两分钟内区分「环境没通」和「代码写错」的手段。这套流程帮我省掉过无数次在业务代码里瞎找原因的夜晚。希望帮到你。
本文还有配套的精品资源，点击获取
