离线查函数文档成败取决于zeal是否装好、docset是否下载全、通信链路是否通；需确保zeal启动并监听50001端口、使用正确中文docset、通过ctrl/cmd+悬停触发跳转。
离线查函数文档，核心就一条：VSCode 本身不存文档，它只负责把函数名发给本地文档工具（如 Zeal 或 Dash），真干活的是后者。所以“离线查阅”成败取决于 Zeal 是否装好、docset 是否下载全、通信链路是否通。
Zeal 没启动或端口不通，跳转必然失败
VSCode 的 vscode-zeal 插件默认通过 http://localhost:50001 和 Zeal 通信。这个端口是 Zeal 启动后自动监听的，不是 VSCode 配的。
- 打开 Zeal，右下角必须显示
Ready；若卡在Starting...，重启 Zeal 或重装 - 终端执行
lsof -i :50001（macOS/Linux）或netstat -ano | findstr :50001（Windows），确认没被其他进程占用 - VSCode 设置里搜
zeal.port，值必须是50001（改了 Zeal 配置才需同步改这里） - 务必用
princejwesley/vscode-zeal，别用旧版 dash 兼容插件——后者对中文 docset 路径转义错误，点开常是空白页
Docset 没装对，搜啥都白搭
Zeal 查的是 docset 自带的 SQLite 索引（docSet.dsidx），不是全文检索。搜 os.path.join 却跳到 C++，大概率是 Python docset 根本没装，或装的是英文版却输中文关键词。
- 在 Zeal 左侧选中对应 docset（如
Python），顶部搜索框直接输函数名，能出结果才算正常 - 要查中文文档，必须手动导入专为中文构建的 docset（如
Python-zh），官网zealdocs.org不提供；可从github.com/zealuser/zh-docsets下载.tgz后解压，Zeal → Preferences → Docsets → + → 选中解压后的文件夹 -
vscode-zeal的zeal.docset设置项不用填，默认按函数名自动匹配已启用的 docset；比如只装了Python和Bash，它就不会去 React 里搜
触发方式不对，根本不会发请求
不是悬停就跳，也不是 Ctrl+Click 自动触发——vscode-zeal 要求显式操作。
- 按住
Ctrl（Windows/Linux）或Cmd（macOS），再鼠标悬停函数名，浮层出现? View in Zeal，点击才发请求 - 光标必须落在有效标识符上：比如
os.path.join中，悬停join才行；悬停os或path会搜模块名，结果不同 - 如果浮层不出现，先检查文件语言模式是否正确（右下角应为
Python，不是Plain Text）
真正容易被忽略的是：Zeal 的 docset 索引是静态生成的，一旦你装了 docset 却搜不到，别急着折腾 VSCode，先在 Zeal 里单独搜一遍——如果 Zeal 里也搜不到，问题 100% 出在 docset 本身，不是插件或配置。
