安装与第一次打开
这篇只覆盖普通交付路径：
- 你拿到的是已经打好的桌面客户端
- 你要把它打开
- 你要确认主界面、应用数据目录和日志都正常
- 然后进入 首次设置
如果你手里只有源码目录、uv 命令、打包脚本或开发环境，那不是普通用户安装路径，请不要把这篇文档当成源码部署手册。
先分清你拿到的是什么
| 你拿到的东西 | 它是什么 | 你现在该怎么做 |
|---|---|---|
macOS .app、.dmg 或压缩包 |
客户端本体 | 安装或解压后双击 Crawler4j.app 打开，不需要再找一个同名目录一起使用 |
Windows .exe 或压缩包 |
客户端本体 | 安装或解压后双击打开 |
| 模块 ZIP 包 | 后续安装到客户端里的业务模块 | 先打开客户端，再去 模块管理 安装 |
| GitHub 仓库地址 | 模块安装源或升级源 | 先确认客户端本体已经装好 |
| 源码目录、终端命令、虚拟环境 | 研发或维护路径 | 不要当成普通用户安装步骤继续走 |
第一次现场最常见的误判有两个：
- 把模块 ZIP 当成客户端本体去双击。
- 把源码目录当成交付物去使用。
开始前至少确认 4 件事
- 你拿到的是客户端本体，而不是只有模块包。
- 你知道现场会使用哪一种外部浏览器：
BitBrowser或VirtualBrowser。 - 你已经拿到模块来源：本地 ZIP 或 GitHub 地址。
- 当前机器允许安装和运行第三方桌面程序。
如果第 2、3 项还没到位，你仍然可以先把客户端打开，但通常还不能跑通完整业务闭环。
第一次打开怎么做
- 按交付说明安装或解压客户端。
- macOS 如解压后看到
Crawler4j.app，直接双击它；不要把是否存在旁边的同名目录当成客户端是否完整的判断条件。 - 等主窗口稳定显示后，不要急着建作业，先确认主界面结构正常。
第一次打开时，这张图只用来确认主界面结构，不用拿图里的统计数字和你现场机器逐项对比。
当前正式客户端统一使用“网页卡片 + 放大镜 + 4j”样式的浅色应用图标；如果你看到系统默认图标、旧版蜘蛛网络样式图标或咖啡杯样式图标，通常说明拿到的不是最新打包产物。
第一次打开后，你应该看到什么
| 位置 | 你会看到什么 | 它是干什么的 |
|---|---|---|
| 顶部状态栏 | 运行中、环境、模块 数量和版本号 |
快速判断当前系统是否有活跃任务、可用环境和当前版本 |
仪表盘 |
统计卡、系统实时日志 | 看整体运行态，不是建任务入口 |
任务监控 |
作业列表、按钮和状态 | 新建作业、执行一次、看详情 |
环境管理 |
环境列表、IP 池管理 | 看浏览器环境和代理/IP 资源 |
模块管理 |
模块列表、安装模块、检查更新 | 模块安装、升级、查看详情 |
使用文档 |
内置文档中心 | 在客户端里直接看使用指南和开发指南 |
系统设置 |
通用、网络、资源、关于 | 配全局设置 |
第一次打开时，即使 任务监控、环境管理、模块管理 还都是空的，也不算异常。对首次启动来说，空列表是正常现象。
什么算“第一次启动正常”
满足下面几条，通常就说明客户端本体已经启动成功：
- 主窗口能稳定打开，不是一闪而退。
- 左侧能看到 6 个主导航入口。
模块管理和系统设置可以正常进入，不会立刻空白或报错。- 应用数据目录已经创建。
- 主日志文件已经生成。
应用数据会写到哪里
桌面客户端启动后，会在当前系统的应用数据目录里写入数据库、日志和模块目录。
- Windows：
%APPDATA%/Crawler4j/ - macOS：
~/Library/Application Support/Crawler4j/ - Linux：
~/.local/share/Crawler4j/
第一次启动后，常见内容如下：
| 路径或文件 | 作用 |
|---|---|
config.db |
保存系统设置和模块配置 |
state.db |
保存任务、环境等运行态信息 |
data.db |
保存模块产出的通用业务数据表 |
logs/crawler4j.log |
主日志文件 |
modules/ |
正式安装的模块目录 |
注意：
- 看见
config.db、state.db，只说明客户端启动过，不说明模块已经安装成功。 data.db存在也不代表你已经跑出了业务结果。- 这些文件只是让你确认“客户端已经启动并产生数据目录”，普通用户不需要手工打开或修改它们。
双击后没反应，先看哪里
macOS 常见问题
- 出现“无法验证开发者”“已阻止打开”等提示
- 从
.dmg里直接打开，没有先拖到正式位置 - 系统安全策略阻止启动
Windows 常见问题
- 被 SmartScreen 或杀毒软件拦截
- 还在压缩包预览里直接双击，没有完整解压
- 当前账号权限不足
不分平台先查这 3 件事
- 应用数据目录有没有创建
logs/crawler4j.log有没有生成- 主程序是不是已经被移动、删掉或路径失效
如果连应用数据目录和日志都完全没有出现，优先怀疑是“程序根本没成功启动”或“系统层拦截”，而不是模块问题。
哪些现象更像“安装/启动问题”
| 现象 | 更像什么问题 | 先去哪里排 |
|---|---|---|
| 双击后完全没主窗口 | 主程序未启动、系统拦截、权限问题 | 系统提示、应用数据目录、主日志 |
| 主窗口能打开，但还不能跑任务 | 大概率还没做首次设置或还没装模块 | 首次设置 |
一进 模块管理 就报错 |
客户端本体问题或交付包问题 | 留证据后转管理员处理 |
| 主窗口正常，但连不上浏览器 | 更像配置问题 | 首次设置 |
第一次打开后，下一步去哪
第一次打开的目标不是把所有页面都点一遍，而是完成两件事：
- 确认客户端本体已经正常启动
- 进入 首次设置 把全局设置核对正确
做完这两件事，再继续模块安装和第一次执行。