快速结论:该报错出现在 InvokeAI 文档站(docs)以 GitHub Pages 子路径(部署 base)发布时:首页链接 href 恰好等于 base 本身,makeHrefToId 未将其归一化为空 id,导致首页在下游按 page id 索引的映射中丢失,并在 index 页的 alsoListedIn 场景抛出异常。优先排查 docs/src/lib/sidebar.mjs 中 base 剥离逻辑。
适用环境:Issue 中已确认:InvokeAI 手动安装、Windows、CPU(无显卡)、版本为 main 分支 commit 89aaeff8c65f7bb1766ccd59a23c7390da95deb1;涉及 docs/src/lib/sidebar.mjs 与 docs/src/lib/sidebar.test.mjs,使用 node --test 运行测试。
最快修复方案:升级到包含 #10269 的版本(该 PR 已合并并关闭本 Issue)。
注意事项:Issue 未给出 #10269 的具体改动细节,也没有列出精确的版本号;升级前请确认所用版本确实包含该合并提交。若自行修改 makeHrefToId,需同时覆盖“href 等于 base”和“href 以 ${basePath}/ 开头”两种情况,避免只修一侧。
问题场景
用户在以部署 base 发布的 InvokeAI 文档站上,使用 GitHub Pages 时首页链接为 /InvokeAI/。文档侧边栏数据由 docs/src/lib/sidebar.mjs 生成,其中 makeHrefToId 负责从 sidebar href 中剥离 base 得到 page id。当 href 等于 base 本身时,函数返回了 InvokeAI 而不是 '',导致依赖 page id 的下游映射(sortAndRelabel 中的 fileNames、addCrossListings 中的 linksById 与 directories)查不到首页,index 页的 alsoListedIn 条目因此报“has no sidebar link”。
报错原文
[bug]: makeHrefToId returns the base path as a page id for the homepage link under a deployment base
has no sidebar link
原因分析
最可能的原因是 makeHrefToId 只在路径以 ${basePath}/ 开头时才剥离部署 base。首页 href 恰好等于 base(不带末尾斜杠匹配),于是未被剥离,得到的是带 base 的字符串而不是空 id。在无 base 的 / 场景下会得到 '',两种部署方式行为不一致,进而使所有以 page id 为键的映射遗漏首页。
环境排查
- 确认 InvokeAI 版本/提交;Issue 基线为
89aaeff8c65f7bb1766ccd59a23c7390da95deb1(main)。 - 确认是否以部署 base 发布文档站(如 GitHub Pages 子路径
/InvokeAI/)。 - 确认
docs/src/lib/sidebar.mjs中makeHrefToId的 base 剥离条件。 - 确认 Node 环境可运行
node --test docs/src/lib/sidebar.test.mjs。
解决步骤
- 先复现基线行为:在
docs/src/lib/sidebar.test.mjs中补充覆盖“href 等于 base 路径”的测试,并运行node --test docs/src/lib/sidebar.test.mjs。Issue 中该场景下 19 个测试有 2 个失败。 - 升级到包含 #10269 的 InvokeAI 版本(或拉取已合并该 PR 的 main),这是 Issue 关闭时确认的修复方式。
- 若需自行修改,可优先尝试调整
makeHrefToId:当剥离后的路径等于剥离后的 base 时返回'',与无 base 时/的结果保持一致;确保原有以${basePath}/开头的剥离逻辑不受影响。 - 升级或修改后重新运行
node --test docs/src/lib/sidebar.test.mjs,确认首页映射与跨列表相关测试全部通过。
验证方法
运行 node --test docs/src/lib/sidebar.test.mjs,确认“homepage href 映射为空 id(有无 base 均一致)”与“base 部署下首页跨列表”这两类测试通过;检查生成的侧边栏数据中首页出现在排序与跨列表映射里,index 页不再抛出“has no sidebar link”。
参考来源
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。


