Page Assist 新手问题排查指南：本地 AI 浏览器扩展 3 大高频故障快速修复

Page Assist 新手问题排查指南：本地 AI 浏览器扩展 3 大高频故障快速修复

【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist

Page Assist 是一款开源浏览器扩展，把本地 AI 模型（Ollama、LM Studio 等）装进每个网页的侧边栏和独立 Web UI，让你在浏览时随时与模型对话、直接提问当前页面内容。本文面向刚接触"浏览器扩展 + 本地模型"的新手，集中解决最容易卡住人的几类故障，全部对照项目真实行为编写。

问题地图：

• 环境自检：动手编译前必查的 6 项清单
• 高频故障一：bun install报command not found，依赖装不上
• 高频故障二：Chrome 提示"无法加载扩展程序"
• 高频故障三：Ollama 返回 403，侧边栏发不出消息
• 高频故障四：快捷键Ctrl+Shift+Y失灵

环境自检：编译 Page Assist 前必查的 6 项清单

先花两分钟过一遍这份清单，后面四个章节里八成问题都能提前避开。

• ✅源码已获取：执行下面的命令后，目录里应能看到README.md和docs/文件夹。

git clone https://gitcode.com/GitHub_Trending/pa/page-assist

• ✅构建工具可用：运行bun --version能输出版本号。没有 Bun 也没关系，项目 README.md 明确允许用npm替代。
• ✅本地模型服务正常：ollama list至少列出一个模型，服务默认监听11434端口。
• ✅端口无其他进程抢占：lsof -i :11434（Windows 可用netstat -ano）的输出应指向 ollama 进程。
• ✅浏览器在支持名单内：对照 docs/browser-support.md，Chrome、Brave、Firefox、Edge 等完整支持侧边栏；Opera、Arc 只能使用 Web UI。
• ✅磁盘空间充足：模型文件较大，建议至少预留 10GB 可用空间。

高频故障一：bun install 报 command not found，一键修复安装

屏幕上的症状

在项目目录敲下bun install，终端立刻回一句bun: command not found；或者安装命令看似跑完，实际没有生成依赖目录，后续编译全线报错。

为什么会卡在这里

终端找不到 Bun，多半是它没装，或者装了但可执行路径（~/.bun/bin）不在PATH环境变量里。Bun 装完后，旧终端窗口不会自动刷新PATH，这是新手最容易忽略的细节。

修复步骤

1. 先运行bun --version判断情况：输出版本号说明只是 PATH 问题，关掉终端重开一个窗口即可；没有任何输出则说明根本没装。
2. 未安装 Bun 时，按 README.md 中 Prerequisites 给出的官方安装方式装上，然后重开终端再跑安装命令。
3. 嫌麻烦可以直接换 npm，项目官方支持：

bun install # Bun 不可用时改用： npm install

4. 安装完依赖后，顺手把版本号再核对一遍，确认构建链路通畅：bun --version与ollama --version都应有输出。

怎么算修好了

终端依次输出 Bun 版本号和 Ollama 版本号，node_modules目录已生成，再没有红色报错。

高频故障二：Chrome 提示"无法加载扩展程序"，最快排查方法

你会看到什么

在chrome://extensions页面点"加载已解压的扩展程序"后，页面顶部弹出红色报错，内容多为"清单文件无效"或"无法找到 manifest.json"。

背后的原因

Chrome 只认编译产物。两个高频诱因：一是选错了目录，把项目根目录或源码目录当成了扩展目录；二是改过代码但没重新编译，build目录里还是旧的、甚至根本不完整的文件。

逐步修复

1. 重新编译，生成最新的扩展产物：

bun run build ls build

2. 确认build目录里存在manifest.json等核心文件。这一步的意义在于：加载目录之前，先证明文件真的在。
3. 回到chrome://extensions，确认右上角"开发者模式"已开启，点"加载已解压的扩展程序"，只选build目录，不要选项目根目录。
4. Firefox 用户路径不同：about:addons→ 扩展 → 管理扩展 → "加载临时附加组件"，直接选build目录下的manifest.json文件（注意是文件，不是目录）。

成功标准

浏览器工具栏出现 Page Assist 图标，扩展页面里没有红色错误条，侧边栏能正常打开。

高频故障三：Ollama 返回 403，侧边栏无法回复

报错长什么样

发消息后侧边栏提示"Direct connection error"（直连失败），或回复里带着403错误。更完整的报错截图说明见 docs/connection-issue.md。

根因：浏览器跨域拦截

浏览器扩展和本地 Ollama 属于不同来源（Origin），默认会被 CORS（跨域资源共享）策略拦截。Page Assist 内置了请求头改写来绕过它，但该改写只对http://127.0.0.1:*和http://localhost:*生效，Ollama 跑在别的地址或端口时就会失手。

两条修复路线

路线 A，在 Page Assist 里改（推荐先试）：

1. 点工具栏扩展图标 → 设置 → Ollama Settings 选项卡。
2. 展开 "Advanced Ollama URL Configuration"。
3. 打开 "Enable or Disable Custom Origin URL"；Ollama 用默认端口就保持原值，换过端口才改 URL。
4. 点 Save 保存，让扩展按正确来源重写请求头。

路线 B，在系统层面放开 Ollama 的来源限制，然后重启 Ollama 服务：

export OLLAMA_ORIGINS="*"

macOS 用launchctl setenv OLLAMA_ORIGINS "*"，Windows 则在系统环境变量中新建OLLAMA_ORIGINS，值填*。

📌 注意副作用：CORS 改写本身可能弄坏个别网站（如 Intel 驱动助手页）。若你恰好遇到这种情况，按 docs/extensions-causing-issue-other-websites.md 关闭"Automatic Ollama CORS Fix"，再配合路线 B 解决 403。

确认解决

重新发送一条消息，模型逐字给出回复，不再出现 403 或连接失败提示。

高频故障四：快捷键 Ctrl+Shift+Y 失灵，重新绑定教程

按了没反应时的表现

在任意网页按下Ctrl+Shift+Y毫无反应，或者触发的是系统截图、输入法切换。右键菜单里的 "Open Page Assist Sidebar" 还能用，说明扩展本身是好的，问题出在按键上。

原因在哪

快捷键注册是全局的，系统、输入法切换键或其他扩展都可能先把它抢走；浏览器快捷键页面里也可能残留旧配置。默认键位说明见 docs/shortcuts.md。

重新绑定

1. Chromium 系浏览器打开chrome://extensions/shortcuts，Firefox 走about:addons→ 设置 → 管理扩展快捷键。这个页面集中展示每个扩展占用的按键，冲突一眼可见。
2. 找到 Page Assist，点 "Open Sidebar" 对应的输入框，按下新组合键。优先选Ctrl+Shift+字母一类，与系统常用键撞车概率最低。
3. 到任意网页按新按键实测一次。
4. 顺手测一下Ctrl+Shift+L（打开 Web UI），两个键位都通才算完整。

💡 修键位前先确认扩展状态正常：右键网页选 "Open Page Assist Sidebar"，能弹出侧边栏再动手改快捷键，可以排除"扩展本身挂了"这个干扰项。

验证通过

新按键一按，侧边栏从页面边缘滑出；旧按键不再误触发其他功能。

辅助工具箱：排查 Page Assist 问题常用的小工具

• bun doctor：Bun 内置诊断，自动检查安装完整性与 PATH 配置，故障一的起手式。
• lsof -i :11434：查看 Ollama 默认端口被谁占用，配合kill结束冲突进程。
• ollama list/ollama ps：前者确认模型已下载，后者确认模型已加载进内存。
• chrome://extensions/shortcuts：浏览器自带的快捷键管理页，可视化查看按键占用，无需第三方工具。
• VS Code：直接打开build/manifest.json，JSON 语法错误（如多余的逗号）会显示红色波浪线。

求助渠道：Issue 模板与社区支持

提交 Issue 前先搜一遍

项目仓库的 Issue 区经常已有人踩过同样的坑，搜索关键词建议带上浏览器名和报错原文（如 "403 Ollama"）。日志里如含 API 密钥，请先打码再贴。

建议的 Issue 格式

[标题] 浏览器 + 一句话症状，例如：Edge 侧边栏发送消息返回 403 [环境] - 系统与版本： - 浏览器与版本： - Page Assist 来源：商店安装 / 源码编译（附版本号） - 本地模型服务：Ollama / LM Studio / 其他，地址与端口 [出现时机] 首次安装即有 / 某次更新后出现 / 一直存在 [已尝试的修复] 对照本指南做到第几章第几步 [截图或报错原文]

社区支持方式

• 官方文档：仓库内 docs/ 目录，按功能分章，如 docs/providers/ollama.md 讲 Ollama 多实例配置，docs/sidebar/ 讲侧边栏的三种打开方式。
• Issue 区：仓库 Issues 提交 bug 与功能请求，维护者会响应并标记状态。
• Discord 社群：README.md 顶部提供了入口，适合实时交流。
• Discussions 讨论区：提问与经验交流，回复通常比 Issue 更快。

【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist