OccupyFinder — 功能介绍

一款 Windows 桌面工具：快速查「端口被谁占了」与「文件被谁锁了」。本机查询、不上传，适合开发调试、运维排障与日常故障定位。

一款 Windows 桌面工具：快速查「端口被谁占了」与「文件被谁锁了」。本机查询、不上传，适合开发调试、运维排障与日常故障定位。

---

一、软件概览

OccupyFinder（端口占用查找器） 解决两类高频痛点：启动服务时报「端口已被占用」，或删除/覆盖文件时提示「文件正在使用」。它把系统底层的连接表与文件占用信息，整理成一张可读的进程列表，并支持一键复制 PID、结束进程（需谨慎）。

核心能力：

• 端口查询：按端口号或「留空列出全部监听」查询 TCP/UDP 占用
• 文件占用：输入路径或浏览/拖入文件，列出持有句柄的进程
• 轻量桌面壳：端口、文件、帮助、设置、关于五个页面；960×640 无边框设计
• 隐私优先：查询在本机 C++ DLL 内完成，无网络请求

端口页：查询 8080；若当前无进程监听，会显示友好空态提示

---

二、工作原理（简述）

工具通过 Windows 系统 API 读取本机网络与文件占用信息：

能力	实现方式
端口占用	GetExtendedTcpTable / GetExtendedUdpTable（IP Helper API）
文件占用	Restart Manager API（RmRegisterResources / RmGetList）
进程详情	按 PID 解析进程名、路径与用户名
结束进程	OpenProcess + TerminateProcess（含系统进程保护）

指定端口时返回该端口全部连接；端口号留空时列出当前所有 TCP LISTEN 与 UDP 绑定 端口。非管理员运行时，部分系统进程可能显示不全。

---

三、主要功能

3.1 页面导航

页面	说明
端口占用	端口号输入、协议筛选、常用端口快捷、结果表格与最近查询
文件占用	路径输入、浏览选择、拖放文件、占用进程列表
帮助	上手步骤、管理员说明、常见问题
设置	默认协议、最近记录条数、自动复制 PID 等
关于	版本与技术组件说明

底部状态栏显示引擎是否就绪、结果条数与上次查询时间。

3.2 端口查询

1. 在 端口占用 页输入端口号，或 留空 后点击「查询」列出全部监听端口
2. 选择协议：全部 / TCP / UDP
3. 也可点击常用端口芯片（80、443、3306、8080、5173 等）快速查询
4. 结果区展示协议、本地地址、连接状态、PID、进程名与路径；可展开详情、复制或结束进程

留空端口号并查询，可一览当前机器上的监听端口（按端口号排序）

3.3 文件占用

1. 输入 文件或文件夹 的完整路径，或点击「浏览…」选择文件
2. 也可将文件 拖到下方拖放区，自动填入路径并查询
3. 若路径存在且无进程占用，显示「未发现占用进程，可尝试删除该文件」
4. 若有占用，表格列出 PID、进程、路径、占用类型与操作按钮

文件页：查询指定路径的占用进程；无占用时显示绿色空态提示

3.4 管理员与权限

• 标题下方黄条提示：非管理员 时部分系统进程可能不可见
• 建议 以管理员身份运行 OccupyFinder，获取更完整的端口与占用列表
• 「结束进程」前请确认影响，避免误杀关键服务

3.5 设置项

选项	说明
默认协议	端口查询默认「全部 / TCP / UDP」
最近查询条数	底部「最近查询」保留的历史数量
查询后自动复制首条 PID	便于粘贴到任务管理器或其他工具

---

四、使用示例

示例 1：开发服务器端口被占（5173 / 8080）

1. 启动 Vite 失败，提示 5173 已被占用
2. 打开 OccupyFinder，输入 5173 或点击常用芯片 5173
3. 查看结果表中 LISTEN 行对应的 node.exe 与 PID
4. 在任务管理器中结束该进程，或确认是否为本机其他终端会话

示例 2：快速浏览本机监听端口

1. 清空 端口号输入框
2. 协议选「全部」，点击「查询」
3. 在结果表中按端口排序浏览，定位异常监听服务

示例 3：无法删除日志文件

1. 切换到 文件占用 页
2. 输入 D:\logs\app.log 或浏览选中该文件
3. 若列表中有进程，记下 PID 与进程名；确认后可结束进程再删除文件

---

五、安装与运行

运行环境

• 系统：Windows 10 及以上（64 位）
• 权限：普通用户可用；管理员身份可获取更完整结果
• 依赖：打包版自带 Electron 运行时与 backend.dll

从安装包运行

安装 OccupyFinder Setup 1.0.0.exe 后，从开始菜单或桌面快捷方式启动即可。

从源码构建（开发者）

cd Frontend
npm install
npm run backend          # 编译 C++ DLL
npm run dev              # Vite + Electron 开发
npm run dist             # 打包安装程序
npm run test:backend     # DLL GTest 回归（26 项）

生成博文配图：

pip install -r scripts/requirements-screenshot.txt
python scripts/auto_screenshot.py --dev

---

六、技术概要

• 界面：Electron + React + TypeScript
• 原生引擎：C++ DLL（sdtech_occupyfinder），经 koffi 绑定 C ABI
• 端口枚举：Windows IP Helper 扩展 TCP/UDP 表
• 文件枚举：Restart Manager；空闲文件返回空数组
• 质量保障：GTest 直接链接 DLL，覆盖边界、JSON 契约与端口/文件集成场景

帮助页：上手说明、管理员提示与 FAQ

设置页：默认协议与行为偏好

---

七、结语

OccupyFinder 把「查端口、查文件锁」收敛进一个小而完整的 Windows 工具：输入或留空、点查询、看进程。若你在某类路径或端口场景下结果不符合预期，欢迎反馈 系统版本、是否管理员、端口/路径样例，便于持续改进。

想了解 DLL 测试与实现细节，请参阅工程内 Backend/Tests 与 npm run test:backend 说明。