快速跑通 Page Assist：新手从克隆到网页聊天的 4 个卡点排查指南

快速跑通 Page Assist：新手从克隆到网页聊天的 4 个卡点排查指南

【免费下载链接】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 连接报错、快捷键冲突。

动手前自检清单

按顺序核对，任何一项不达标就先补上，再往下排障：

1. 终端能跑bun --version并返回版本号；若没装 Bun，用npm代替即可。
2. 终端能跑ollama --version并返回版本号，说明本地 AI 服务（Ollama，一个在你电脑上跑大语言模型的后台程序）已装好。
3. 仓库已克隆，且执行bun install后生成了node_modules目录。
4. 执行bun run build后生成了build目录——加载扩展时要选它，不是仓库根目录。
5. 浏览器是 Chrome、Brave、Edge、Firefox 等受支持版本；Opera 和 Arc 不支持侧边栏功能。
6. Ollama 默认跑在localhost:11434时 Page Assist 会自动识别，无需额外配置。

装依赖卡住或报 Bun 相关错误？换 npm 兜底

触发场景：执行bun install时终端报版本不兼容、网络超时，或压根找不到bun命令。

快速判断：单独运行bun --version。若报「command not found」或版本号过旧，就是运行时的锅，不是代码问题。

处置动作：

1. 打开终端，确认能打印bun --version；不行就按官方说明装好并把路径加进环境变量。
2. 仍报错时，把后续所有命令里的bun换成npm：npm install装依赖、npm run build构建。
3. 构建命令是串联的，npm run build会依次产出 Chrome、Firefox、Edge 三个版本的扩展。

验证收尾：build目录下出现chrome、firefox、edge三个子目录，各含一个manifest.json，就算构建成功。

加载扩展提示无法加载？三步定位目录

触发场景：按流程去浏览器加载刚构建的扩展，却报「无法加载扩展程序」或找不到 manifest。

快速判断：检查你选中的文件夹里有没有manifest.json。选错层级（选了仓库根目录而非build下的浏览器子目录）是最常见原因。

处置动作：

1. 打开扩展管理页：Chrome 系访问chrome://extensions，Firefox 访问about:addons。
2. Chrome 系打开右上角「开发者模式」开关；Firefox 点击「管理您的扩展程序」再点「加载临时附加组件」。
3. 选中build目录下对应浏览器的子目录（Chrome 选chrome，Firefox 选firefox里的manifest.json），别选仓库根目录。

验证收尾：扩展列表出现 Page Assist 且状态为「已启用」，点击工具栏图标能弹出 Web UI 即成功。

发消息报 403 或连接被拒？Ollama 跨域拦截

触发场景：侧边栏里点发送，消息发不出去，提示 403 或直接连接失败。

快速判断：浏览器能正常打开http://localhost:11434说明 Ollama 本身活着；报 403 就是跨域（CORS，浏览器阻止不同来源页面互访）拦截了扩展的请求。

处置动作：

1. 打开 Page Assist，点工具栏图标进入 Web UI，再点设置图标。
2. 切到 Ollama Settings 选项卡，展开「Advance Ollama URL Configuration」。
3. 打开「Enable or Disable Custom Origin URL」开关，自定义地址默认保留不动，点 Save。
4. 若 Ollama 改过端口，再把 Custom Origin URL 改成对应端口。

验证收尾：重新发一条消息，能收到模型回复即通。仍报错时，在系统环境变量里设OLLAMA_ORIGINS=*并重启 Ollama 服务再试。

快捷键没反应或被抢？去浏览器改映射

触发场景：按默认键Ctrl+Shift+Y想开侧边栏没反应，或触发了别的应用/扩展。

快速判断：确认浏览器支持侧边栏（Opera、Arc 除外）；再确认没被其他扩展占用同一组合键。

处置动作：

1. Chrome 系访问chrome://extensions/shortcuts，找到 Page Assist。
2. 把「Open Sidebar」改成一个空闲组合键，避开系统常用键。
3. Firefox 在about:addons里点设置图标，进「Manage Extension Shortcuts」改。

验证收尾：在任意网页按新按键，侧边栏能弹出即生效。应用内快捷键（如Ctrl+E切换对话模式）不受浏览器影响，无需改。

防坑清单

• 构建产物分三份，加载时认准与当前浏览器同名的子目录，选错层级是「无法加载」的头号原因。
• bun出问题别死磕，npm全流程可平替，README 也明确给了这个退路。
• 跨浏览器复制经验时先看支持矩阵：侧边栏在 Opera、Arc 上不可用，不是 bug。
• 改了 Ollama 端口后记得同步更新 Page Assist 里的自定义 Origin URL，否则自动识别失效。
• 临时附加（Firefox 的 Load Temporary Add-on）重启浏览器后会失效，长期用请走正式发布渠道安装。

完整配置项与更多报错场景，见 docs/settings.md 与 docs/connection-issue.md。

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