# browser-api-capture **Repository Path**: zhao_dong_1/browser-api-capture ## Basic Information - **Project Name**: browser-api-capture - **Description**: No description available - **Primary Language**: TypeScript - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-20 - **Last Updated**: 2026-04-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 浏览器接口调用捕获工具 ## 📖 目录 1. [项目简介](#项目简介) 2. [功能特性](#功能特性) 3. [快速开始](#快速开始) 4. [脚本说明](#脚本说明) 5. [使用指南](#使用指南) 6. [技术架构](#技术架构) 7. [环境配置](#环境配置) 8. [打包分享](#打包分享) 9. [常见问题](#常见问题) 10. [贡献指南](#贡献指南) --- ## 项目简介 这是一个功能强大的浏览器API调用捕获工具，帮助开发者通过分析API请求、响应和错误快速解决Web应用问题。 ### 🎯 主要用途 - Web应用开发调试 - API接口问题定位 - 接口文档生成 - 性能分析和优化 - 安全审计 - 第三方系统集成测试 --- ## 功能特性 ### 核心功能 - 🚀 **浏览器自动化控制** - 自动启动Chrome浏览器并导航到指定URL - 📊 **实时API捕获** - 自动捕获所有API请求和响应 - 🔍 **多维度过滤** - 支持按资源类型和URL模式过滤请求 - 📋 **详细信息展示** - 查看完整的请求和响应详情（头部、主体、状态码） - 💾 **数据导出** - 支持JSON格式导出捕获数据 - 📄 **ClaudeCode集成** - 生成专门用于ClaudeCode分析的问题报告 - ✏️ **用户补充** - 支持手动补充服务器错误信息和备注 - 🔄 **CURL命令** - 一键生成可执行的CURL命令 ### 界面特色 - 🎨 **简洁美观的界面** - 基于React的现代化UI设计 - 📱 **响应式布局** - 自适应不同屏幕尺寸 - ⚡ **实时更新** - WebSocket实现数据的实时传输 - 🎯 **标签页导航** - 清晰的信息分类展示 --- ## 快速开始 ### 🎯 如果你收到的是开箱即用版本 **Windows用户：** ```bash start-all.bat ``` **Linux/macOS用户：** ```bash chmod +x *.sh ./start-all.sh ``` 然后访问：**http://localhost:5173** ### 🔧 如果需要先配置环境 **Windows用户：** ```bash # 1. 配置环境 setup.bat # 2. 启动服务 start-all.bat ``` **Linux/macOS用户：** ```bash # 1. 配置环境 chmod +x setup.sh ./setup.sh # 2. 启动服务 ./start-all.sh ``` --- ## 脚本说明 ### 日常使用脚本 | 脚本 | 功能 | 使用场景 | | -------------------------------- | ------------------ | --------------------------- | | `start-all.bat` / `start-all.sh` | 同时启动后端和前端 | **日常使用** - 最常用的脚本 | | `stop.bat` / `stop.sh` | 安全停止服务 | 使用完成后停止 | ### 单独启动脚本 | 脚本 | 功能 | 使用场景 | | ------------------------------------------ | -------------- | ------------ | | `start-backend.bat` / `start-backend.sh` | 仅启动后端服务 | 单独调试后端 | | `start-frontend.bat` / `start-frontend.sh` | 仅启动前端服务 | 单独调试前端 | ### 维护脚本 | 脚本 | 功能 | 使用场景 | | ---------------------------------------- | -------------- | ------------------ | | `check-project.bat` / `check-project.sh` | 检查项目完整性 | 怀疑项目有问题时 | | `setup.bat` / `setup.sh` | 从网络下载依赖 | 需要重新安装依赖时 | ### 打包分享脚本 | 脚本 | 功能 | 使用场景 | | ------------------------------------ | ---------------- | ---------- | | `prepare-now.bat` / `prepare-now.sh` | 准备开箱即用版本 | 打包前准备 | | `package-now.bat` / `package-now.sh` | 打包整个项目 | 打包分享 | --- ## 使用指南 ### 完整操作流程 #### 1. 启动项目 ```bash # Windows start-all.bat # Linux/macOS ./start-all.sh ``` 访问 **http://localhost:5173** #### 2. 配置捕获 在网页中： - 输入要测试的网站URL - 选择要捕获的资源类型（XHR、Fetch、图片、CSS、JS等） - （可选）设置URL模式过滤 #### 3. 开始捕获 点击"**开始捕获**"按钮，Chrome浏览器会自动启动并导航到指定URL。 #### 4. 操作测试 在打开的Chrome浏览器中进行正常操作，触发各种API请求。 #### 5. 查看记录的信息 - 在网页左侧会看到一个列表，显示所有记录的请求 - 点击任意一个请求，右侧会显示详细信息 - 可以切换标签页查看不同内容： - **请求**：发送给服务器的信息 - **响应**：服务器返回的信息 - **CURL命令**：可以直接复制的测试命令 - **补充信息**：可以自己添加问题描述和备注 #### 6. 保存数据 - 点击"**停止捕获**"结束会话 - 点击"**导出API调用**"保存JSON文件 - 点击"**生成ClaudeCode分析**"生成分析报告 #### 7. 停止服务 ```bash # Windows stop.bat # Linux/macOS ./stop.sh ``` **说明：** - `stop.bat` / `stop.sh` - 仅停止占用3000和5173端口的进程（本项目服务） ### API详情说明 #### 请求标签 - **方法**: HTTP方法（GET、POST等） - **URL**: 请求的完整地址 - **头部**: HTTP请求头 - **主体**: 请求体内容 - **时间戳**: 请求发送时间 #### 响应标签 - **状态**: HTTP状态码和状态文本 - **头部**: HTTP响应头 - **主体**: 响应体内容 - **错误**: 错误信息（如果有） - **时间戳**: 响应时间 - **持续时间**: 请求耗时 #### CURL命令标签 - **CURL命令**: 完整的CURL调用命令 - **请求示例**: JSON格式的请求体示例 - **响应示例**: JSON格式的响应体示例 - 每个部分都有独立的"复制"按钮 #### 补充信息标签 - **服务器报错信息**: 从服务器日志复制的错误信息 - **备注**: 描述期望的行为或问题 --- ## 技术架构 ### 技术栈 #### 后端 - **Node.js** - JavaScript运行时 - **Express** - Web应用框架 - **Puppeteer** - 浏览器自动化 - **WebSocket** - 实时通信 - **TypeScript** - 类型安全 #### 前端 - **React 18** - UI框架 - **TypeScript** - 类型安全 - **Vite** - 构建工具 ### 项目结构 ``` browser-api-capture/ ├── src/ │ ├── backend/ # 后端代码 │ │ ├── index.ts # 入口文件 │ │ ├── server.ts # Express服务器 │ │ ├── puppeteerManager.ts # 浏览器控制 │ │ ├── apiCapture.ts # API捕获逻辑 │ │ ├── testServer.ts # 测试服务器 │ │ └── utils/ │ │ └── logger.ts # 日志工具 │ ├── frontend/ # 前端代码 │ │ ├── src/ │ │ │ ├── main.tsx # 入口文件 │ │ │ ├── App.tsx # 主应用 │ │ │ ├── components/ # React组件 │ │ │ │ ├── ApiDetail.tsx │ │ │ │ ├── ApiList.tsx │ │ │ │ └── BrowserControl.tsx │ │ │ ├── types/ │ │ │ │ └── index.ts │ │ │ ├── types.ts # 类型定义 │ │ │ └── index.css # 全局样式 │ │ ├── dist/ # 前端构建输出 │ │ ├── index.html │ │ ├── package.json │ │ ├── tsconfig.json │ │ ├── tsconfig.node.json │ │ └── vite.config.ts │ └── shared/ # 共享代码 │ └── types.ts # 类型定义 ├── dist/ # 后端编译输出 │ ├── backend/ # 后端JS文件 │ └── shared/ # 共享JS文件 ├── *.bat # Windows启动脚本 ├── *.sh # Linux/macOS启动脚本 ├── package.json # 后端依赖 ├── package-lock.json ├── tsconfig.json # TypeScript配置 ├── README.md # 项目文档 └── .gitignore ``` ### 架构图 ``` ┌─────────────────────────────────────────────────────────────┐ │ 用户浏览器 │ │ (React + Vite) │ │ http://localhost:5173 │ └────────────────────────────┬────────────────────────────────┘ │ WebSocket (ws://localhost:3000) │ ┌────────────────────────────▼────────────────────────────────┐ │ 后端服务器 (Express) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ API路由层 (/api/*) │ │ │ │ - /api/health - 健康检查 │ │ │ │ - /api/capture/start - 开始捕获 │ │ │ │ - /api/capture/stop - 停止捕获 │ │ │ │ - /api/capture/api-calls - 获取API列表 │ │ │ │ - /api/capture/export - 导出数据 │ │ │ └─────────────────────────────┬───────────────────────┘ │ │ │ │ │ ┌─────────────────────────────▼───────────────────────┐ │ │ │ API捕获管理层 (apiCapture.ts) │ │ │ │ - 管理捕获的API调用数据 │ │ │ │ - 生成ClaudeCode分析报告 │ │ │ └─────────────────────────────┬───────────────────────┘ │ │ │ │ │ ┌─────────────────────────────▼───────────────────────┐ │ │ │ 浏览器控制层 (puppeteerManager.ts) │ │ │ │ - 启动和关闭Chrome浏览器 │ │ │ │ - 监听网络请求 │ │ │ │ - URL模式和资源类型过滤 │ │ │ └───────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 环境配置 ### 系统要求 - **Node.js**: v14 或更高版本 - **浏览器**: Google Chrome（必须已安装） - **内存**: 建议至少 4GB RAM - **网络**: 用于首次安装依赖（后续离线可用） ### 端口说明 - **3000**: 后端服务端口 - **5173**: 前端开发服务器端口 如需修改，可编辑以下文件： - 后端端口: `src/backend/server.ts` - 前端端口: `src/frontend/vite.config.ts` --- ## 打包分享 ### 打包流程（分享者） #### 第一步：准备项目 ```bash # Windows prepare-now.bat # Linux/macOS chmod +x prepare-now.sh ./prepare-now.sh ``` 这个脚本会自动： - ✓ 安装后端依赖（如果未安装） - ✓ 安装前端依赖（如果未安装） - ✓ 构建后端 - ✓ 构建前端 #### 第二步：测试项目（推荐） ```bash # 启动测试 start-all.bat # 确认正常后停止 stop.bat ``` #### 第三步：打包 ```bash # Windows package-now.bat # Linux/macOS chmod +x package-now.sh ./package-now.sh ``` 打包完成后，你会在项目文件夹的上一级看到类似这样的文件： - Windows: `browser-api-capture-OUT-OF-BOX-日期时间.zip` - Linux/macOS: `browser-api-capture-OUT-OF-BOX-日期时间.tar.gz` #### 第四步：分享 把这个压缩包发给你的朋友！ ### 接收者使用方法 #### Windows用户 ```bash 1. 解压压缩包 2. 进入文件夹 3. 双击运行: start-all.bat 4. 浏览器访问: http://localhost:5173 5. 用完后运行: stop.bat ``` #### Linux/macOS用户 ```bash 1. 解压压缩包 2. 进入文件夹 3. chmod +x *.sh 4. 运行: ./start-all.sh 5. 浏览器访问: http://localhost:5173 6. 用完后运行: ./stop.sh ``` ### 注意事项 1. **平台兼容性**: 建议在相同操作系统间分享（Windows→Windows） 2. **文件大小**: 开箱即用版本通常有几十MB大小 3. **备选方案**: 如果接收者遇到依赖问题，可运行 `setup.bat` 重新下载 --- ## 常见问题 ### 启动问题 **Q: 双击脚本没有反应？** A: 请尝试右键选择"以管理员身份运行"（Windows） **Q: 提示找不到npm或node？** A: 1. 确认已安装Node.js 2. 重启命令行窗口 3. 从官网重新安装Node.js **Q: 端口被占用？** A: 1. 关闭占用3000或5173端口的程序 2. 或运行 `stop.bat` 停止本项目的进程 ### 浏览器问题 **Q: Chrome浏览器无法启动？** A: 1. 确认Chrome已安装 2. 检查是否有其他Chrome实例在运行 3. 尝试先关闭所有Chrome窗口 ### 使用问题 **Q: API调用没有被捕获？** A: 1. 检查资源类型过滤设置 2. 检查URL模式设置 3. 确认网站确实在发送API请求 **Q: 重复的API调用？** A: 系统已实现去重逻辑，每个请求只会被捕获一次 **Q: 停止捕获后界面卡住？** A: 1. 尝试运行 `stop.bat` 停止服务 2. 手动关闭控制台窗口 3. 重启项目 ### 导出问题 **Q: 导出文件为空？** A: 确保已捕获到API调用，检查是否有数据 **Q: ClaudeCode分析文件格式不对？** A: 系统已优化格式，每个API调用都有完整的method、url、status等字段 --- ## 贡献指南 欢迎贡献代码或提出建议！ ### 开发流程 1. Fork 项目 2. 创建分支 (`git checkout -b feature/your-feature`) 3. 提交更改 (`git commit -m 'Add some feature'`) 4. 推送到分支 (`git push origin feature/your-feature`) 5. 创建 Pull Request ### 代码规范 - 遵循 TypeScript 最佳实践 - 保持代码风格一致 - 添加适当的注释 - 编写测试用例 --- ## 版本信息 - **版本**: v1.0.0 - **最后更新**: 2026-04-20 - **许可证**: MIT --- ## 联系方式 如有问题或建议，请通过以下方式联系： - 提交GitHub Issue - 发送邮件给项目维护者 - 查看项目wiki --- **祝你使用愉快！🎉**