1. z-reader 搜索笔趣阁返回空结果先搞清楚请求链路到底断在哪z-reader 是 VS Code 里一个把小说阅读器塞进编辑器侧边栏的插件支持多个书源其中笔趣阁源是很多人用得最多的一个。它的工作方式并不复杂你在插件面板里输入关键词插件调用书源驱动里的search()方法拼出一个搜索 URL用got发 HTTP 请求拿到 HTML 后用cheerio解析出书名、作者、章节链接最后渲染成树形节点。所以「搜索无效」这个现象本质上是这条链路上某一环断了。我遇到的情况是输入书名回车面板转一下圈然后什么都没有既不报错也不出结果。打开 VS Code 的开发者工具帮助 → 切换开发人员工具看 Console能看到一条HTTPError: Response code 403 (Forbidden)的警告。这就是关键线索——请求发出去了但目标站点拒绝了。为什么会被拒常见原因有三类。第一类是站点换了域名或改了页面结构插件里写死的DOMAIN常量指向了一个已经失效或者被风控的地址第二类是请求头缺失很多站点会检查User-Agent、Referergot默认的 UA 很容易被识别成脚本流量第三类是插件配置本身有问题比如书源开关没打开、搜索超时太短、代理设置冲突。这篇要解决的就是第一类和第二类交织的典型故障搜索接口返回 403导致cheerio拿到的是错误页而不是结果页.result-list .result-item选择器匹配不到任何元素result数组为空面板自然一片空白。适合正在用 z-reader 看小说、突然发现搜索失灵、又不想干等插件作者更新的读者。下面我会从定位插件安装路径开始一步步改驱动文件、补请求头、验证结果把搜索功能恢复回来。需要说明的是改插件源码属于本地修补插件升级后会被覆盖所以改完最好记一下改动点。另外如果你只是想快速验证某个模型或接口能不能通可以顺手用 TaoToken 的模型对话页面测一下请求链路排除是不是本地网络环境的问题地址是 https://taotoken.net/api 这个后面配置章节会再提。2. 定位 z-reader 安装目录与 biquge 驱动文件403 forbidden 排查前置动手之前先把「案发现场」找出来。VS Code 插件都装在用户目录下的.vscode/extensions里命名规则是发布者.插件名-版本号。z-reader 的发布者是aooiu所以路径长这样C:\Users\你的用户名\.vscode\extensions\aooiu.z-reader-1.0.3macOS 和 Linux 用户在~/.vscode/extensions/aooiu.z-reader-1.0.3。版本号可能不是 1.0.3以你本地实际目录为准。如果找不到可以在 VS Code 里右键插件 → 扩展设置或者用命令面板执行Extensions: Show Installed Extensions看版本。进去之后关注out目录这是 TypeScript 编译后的产物插件运行时加载的就是这里。笔趣阁驱动在out/reader/driver/biquge/index.js同目录下通常还有index.js.map那是源码映射改代码不用管它。打开index.js你会看到开头定义了两个常量const DOMAIN https://www.sobiquge.com; const DOMAIN_M https://m.sobiquge.com;DOMAIN用于章节列表和正文抓取DOMAIN_M是移动端域名用于搜索。搜索方法里拼的是DOMAIN_M /search.php?q encodeURI(keyword)。如果这个移动端域名被风控或者改版搜索就会 403 或返回空结构。在改之前建议先手动验证一下这个 URL 到底返回什么。用浏览器直接访问https://m.sobiquge.com/search.php?q斗破苍穹看是正常出结果、跳转到别的域名还是直接 403。这一步能帮你确认问题出在域名还是请求头。如果浏览器能打开但插件不行那基本就是请求头的问题如果浏览器也打不开那就是域名失效需要换地址。顺便说一句排查这类「请求发出去但拿不到数据」的问题思路和调 API 是一样的先确认目标可达再确认请求格式最后看响应解析。如果你平时也在用大模型 API 做开发TaoToken 的接入文档里对请求头、鉴权、错误码的说明比较清楚可以对照着理解 HTTP 层的排查逻辑文档入口在 https://taotoken.net/api 配合 API Keys 页面 https://taotoken.net/api-keys 一起看更直观。找到文件后先别急着改复制一份index.js备份改坏了能还原。接下来进入实际修改。3. 可复制的 settings.json 与驱动补丁修复搜索请求配置修复分两部分一是给got请求补上合理的请求头降低被判定为脚本流量的概率二是把搜索域名和选择器对齐到当前可用的页面结构。先看插件层面的配置。z-reader 的设置项可以在 VS Code 的settings.json里配。按CtrlShiftP打开命令面板输入Preferences: Open User Settings (JSON)加入下面这段{ z-reader.requestTimeout: 15000, z-reader.maxSearchResults: 30, z-reader.enableBiquge: true, z-reader.userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 }注意不同版本的 z-reader 配置键名可能略有差异如果编辑器提示未知配置项说明你的版本不支持直接删掉那一行即可不影响核心修复。requestTimeout调大是为了避免网络慢时请求被提前掐断userAgent如果插件支持就填上不支持就在驱动里硬编码。核心改动在out/reader/driver/biquge/index.js。找到search方法把请求部分改成带请求头的写法search(keyword) { return __awaiter(this, void 0, void 0, function* () { const result []; try { const res yield got(DOMAIN_M /search.php?q encodeURI(keyword), { headers: { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36, Referer: DOMAIN_M /, Accept: text/html,application/xhtmlxml,application/xml;q0.9,*/*;q0.8, Accept-Language: zh-CN,zh;q0.9 }, timeout: 15000, retry: 1 }); const $ cheerio.load(res.body); $(.result-list .result-item.result-game-item).each(function (i, elem) { const title $(elem).find(a.result-game-item-title-link span).text(); const path $(elem).find(a.result-game-item-pic-link).attr(href); if (title path) { result.push(new TreeNode_1.TreeNode(Object.assign({}, TreeNode_1.defaultProblem, { type: .biquge, name: title, isDirectory: true, path }))); } }); } catch (error) { console.warn([z-reader][biquge] search failed:, error.message); } return result; }); }几个改动点值得说明。第一加了headers尤其是User-Agent和Referer这是绕过基础风控最有效的一步。第二timeout和retry让请求更稳。第三原来代码里$(elem).find(a.result-game-item-pic-link).attr().href这种写法在attr()返回 undefined 时会抛异常我改成了.attr(href)并加了空值判断避免单个节点解析失败导致整个搜索崩掉。第四catch里打印了具体错误信息方便下次排查。如果你发现m.sobiquge.com本身已经不可用需要换成当前有效的移动端域名。判断方法还是浏览器访问能正常出搜索结果的域名就填进DOMAIN_M。章节和正文用的DOMAIN同理两个域名可能不同别搞混。改完保存文件。这里有个坑VS Code 可能缓存了插件代码直接重载窗口不一定生效。稳妥做法是完全退出 VS Code 再打开或者用命令面板执行Developer: Reload Window。如果还不行检查是不是有多个版本的 z-reader 目录改错了那一个。4. 验证搜索请求与成功结果从 Console 日志到面板出书改完之后要验证不能只看「面板有没有出东西」要确认整条链路都通了。验证分三步。第一步看请求是否成功。打开 VS Code 开发者工具帮助 → 切换开发人员工具切到 Console 面板在 z-reader 里输入关键词搜索。如果修复生效Console 里不应该再出现403或search failed的警告。如果还有报错把错误信息完整读一遍Response code 403说明请求头还不够ETIMEDOUT说明网络或超时问题Cannot read properties of undefined说明选择器没匹配到是页面结构变了。第二步看解析结果。在 Console 里可以临时加一行调试或者直接在搜索后观察面板。正常情况下搜索「斗破苍穹」这类热门书面板会列出若干条结果每条是一个可展开的目录节点。点开节点应该能看到章节列表再点章节正文能加载出来。如果搜索出结果但点进去章节为空说明getChapter里的DOMAIN或选择器#list dd有问题需要单独排查。第三步用命令行独立验证接口。这一步能帮你区分是插件问题还是站点问题。在终端里执行curl -s -o /dev/null -w %{http_code}\n \ -H User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 \ -H Referer: https://m.sobiquge.com/ \ https://m.sobiquge.com/search.php?q%E6%96%97%E7%A0%B4%E8%8B%8D%E7%A9%B9返回200说明请求头方案有效返回403说明还需要调整。想看内容就加-s去掉-o /dev/null直接输出 HTML检查里面有没有result-list这个 class。这一步和调 API 时用 curl 验证鉴权是一个道理先确认服务端认不认你的请求再谈客户端解析。如果你在验证过程中想顺便确认自己的网络出口、请求头构造是否正确可以拿一个标准 API 做对照测试。TaoToken 的模型对话页面 https://taotoken.net/api 可以直接发一条测试请求看返回是否正常这样能快速排除「本地网络整体不通」这种低级问题。确认网络没问题后再回到 z-reader 的排查上思路会清晰很多。实测下来补上请求头之后搜索基本能恢复。如果站点后续又改版选择器失效那就需要重新用浏览器开发者工具看新的 DOM 结构更新cheerio的选择器。这类修补是持续性的建议把改动点记在笔记里。5. 常见报错对照排查401、local proxy failed、reading choices 与 OAuth修 z-reader 的过程中你可能会撞上一些看起来不相关的报错。这里做一张对照表把常见错误和对应原因列清楚避免走弯路。报错信息出现位置原因处理方式Response code 403 (Forbidden)z-reader Console请求头缺失或域名被风控补 User-Agent/Referer或换可用域名ETIMEDOUT/Request timed outz-reader Console网络慢或超时设置过短调大requestTimeout加retryCannot read properties of undefined (reading href)z-reader Console选择器匹配失败页面结构变了用浏览器重新确认 DOM 结构更新选择器401 UnauthorizedAPI 调用场景Key 缺失、过期或格式错误检查 API Keys 页面重新生成并填入local proxy failed本地开发工具本地代理配置冲突或端口占用关闭冲突代理检查环境变量reading choices相关报错模型接口返回解析响应结构与预期不符打印原始响应核对字段名OAuth授权失败第三方登录/授权回调地址或 token 过期重新走授权流程检查回调配置重点说几个。401和OAuth通常出现在你调外部 API 的场景和 z-reader 本身无关但如果你在同一个 VS Code 里既看小说又写代码调接口Console 里混着各种报错容易看花眼建议按来源过滤。local proxy failed多半是本地网络工具或环境变量HTTP_PROXY在捣乱z-reader 的got请求会继承这些设置导致请求发不出去。检查方法是在终端执行echo $HTTP_PROXYWindows 用echo %HTTP_PROXY%有值就临时清掉再试。reading choices这类报错一般出现在解析模型返回的 JSON 时字段名对不上。处理办法是把原始响应完整打印出来逐字段核对别靠猜。这和改 z-reader 选择器是一个思路先看真实数据长什么样再写解析逻辑。还有一个容易忽略的点如果你在 z-reader 里配置了自定义书源或者用了 Cline、CC Switch 这类工具做 MCP 接入配置里的 Base URL、Key、Model ID 三件套必须齐全且一致。缺一个就会报鉴权或连接错误。以 Codex 的auth.json为例结构大致是{ base_url: https://taotoken.net/api, api_key: sk-你的密钥, model: claude-sonnet-4-20250514 }Base URL 指向接口地址Key 从 API Keys 页面获取Model ID 要和平台支持的模型名一致。三者任何一个写错请求都会失败。排查时优先核对这三项比盲目改代码高效得多。如果你需要长期做编码类任务Coding Plan 页面 https://taotoken.net/coding-plan 里有更完整的配置说明可以对照检查。6. 把搜索修好之后z-reader 稳定使用的几个实用习惯搜索恢复只是第一步想让它长期稳定有几个习惯值得养成。第一插件升级前先备份改动。z-reader 更新会覆盖out目录你改的index.js会没。建议把改好的文件另存一份升级后对比差异再合并。如果改动多可以用git在插件目录初始化一个仓库每次改完提交一次升级后diff一下就知道哪些要重新打补丁。第二域名和选择器要定期检查。书源站点改版是常态今天能用的选择器明天可能就失效。判断方法很简单搜索出结果但点进去空白多半是章节或正文的选择器变了搜索直接空多半是搜索接口或域名变了。用浏览器开发者工具看新结构更新对应选择器即可。第三请求头别写死单一 UA。有些站点会针对特定 UA 做限制可以准备两三个常见浏览器的 UA 轮换。got支持在请求时动态设置改起来不难。第四善用 Console 日志。我在补丁里加了console.warn打印错误信息这是排查问题的第一手资料。遇到问题先看 Console比到处搜教程快得多。日志里如果出现search failed后面跟的错误信息基本能定位到具体环节。第五区分「插件问题」和「环境问题」。如果 z-reader 搜索失败同时你发现其他需要联网的插件或 API 调用也不正常那大概率是本地网络或代理的问题不是插件本身。这时候先检查网络环境再回来改代码。用 TaoToken 的模型对话页面发一条测试请求能快速判断网络是否通畅地址是 https://taotoken.net/api 配合接入文档 https://taotoken.net/api 一起看排查思路会更系统。最后提醒一句改插件源码是本地行为插件作者更新后你的改动可能失效也可能和新版本冲突。如果作者已经修复了这个问题优先用官方版本别一直维护自己的补丁。只有当官方长期不更新、而你又确实需要这个功能时本地修补才是合理选择。把改动记录清楚下次遇到类似问题你就能更快定位到是请求头、域名还是选择器的问题而不是从头再排查一遍。