企业官网建设流程全解析

Page Assist 排障指南：新手 5 分钟解决扩展加载失败、模型连不上等常见问题

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

Page Assist 是一个开源的 Chrome 扩展，把你在本地跑的 AI 模型（比如 Ollama）变成一个能贴在任何网页侧边栏、还能开出 Web UI 的对话助手。这篇 Page Assist 常见问题速查，专门帮你把新手最容易卡住的几步排掉：从装环境、加载扩展，到第一次发消息、调快捷键。你照着"症状速查表"对号入座，大多数坑 5 分钟内就能过掉。

症状速查表

一、环境准备：先把 Bun 和 Ollama 装明白 🛠️

Page Assist 自己不需要联网服务，但它靠两样东西干活：用 Bun 把扩展构建出来，用 Ollama 在本地跑模型。先把这两样确认好，后面才不会白忙。

bun 命令找不到

现象：你在终端敲bun --version，回你command not found或"不是内部或外部命令"。

原因：多半是 Bun 压根没装，或者装完了但它的安装目录没进环境变量，当前终端还没刷新。

操作：

• 按 Bun 官方说明把运行时装上。
• 把 Bun 的 bin 目录加进PATH。
• 关掉当前终端，重新开一个再验证，别在旧窗口里纠结。

做完这一步，bun --version应该能正常吐出版本号，而不是报错。

5 分钟确认 Ollama 本地模型真的在跑

现象：ollama list报连不上服务，或者模型列表空空的。

原因：Ollama 的后台服务没在运行，装好客户端不等于服务就在监听。

操作：

• 终端跑ollama serve把服务拉起来，或确认它已设成开机自启。
• 另开一个窗口跑ollama list，看看有没有模型。
• 一个都没有就先ollama pull拉一个你常用的模型下来。

参考仓库里的 Ollama 提供方说明。做完这步，ollama list应该能列出你已拉取的模型名，这就说明本地这一侧是通的。

二、安装与加载：把扩展真正装进浏览器

提示"无法加载扩展程序"时

现象：你点了"加载已解压的扩展程序"，浏览器弹"无法加载扩展程序"，扩展列表里什么都没有。

原因：几乎都是两件事之一——选错了目录（选成了仓库根目录，里面没有manifest.json），或者根本没开开发者模式。

操作：

• 打开扩展管理页chrome://extensions，先把右上角的开发者模式打开。
• 先跑一次bun run build，确认生成出build目录。
• 点"加载已解压的扩展程序"，选build目录本身，不是它外面的仓库文件夹。
• 进去瞄一眼build里确实有manifest.json再点确定。

做完这步，扩展列表里应该稳稳出现 Page Assist，图标不再是报错状态。

加载后浏览器里找不到图标

现象：扩展明明装上了，工具栏却翻遍也找不到 Page Assist。

原因：新装的扩展默认被折叠进拼图（扩展）图标里，不占工具栏。

操作：

• 点工具栏右上角的拼图图标。
• 在弹出列表里找到 Page Assist，点它旁边的固定图钉。

做完这步，工具栏应该固定出现 Page Assist 图标，点一下就能开 Web UI。

三、首次运行：第一次和模型说上话 ✨

模型列表是空的

现象：Web UI 或侧边栏里，模型下拉框空空如也，没法选。

原因：要么 Ollama 没在跑（回上面"环境准备"那节），要么你确实还没拉过任何模型。

操作：

• 默认情况下 Ollama 跑在localhost:11434，Page Assist 会自动探测，不用额外填地址。
• 确认 Ollama 服务在线（ollama list能看到东西）。
• 没有就ollama pull一个模型，再回扩展里刷新。

做完这步，模型下拉框里应该出现你刚拉取的模型名，可以选中了。

发消息一直转圈或直接报错

现象：消息发出去转半天，最后弹出 403 或连接失败的提示。这是 Ollama 本地模型连接里最高频的一道坎。

原因：浏览器扩展要和 Ollama 通信，但浏览器默认拦截跨域请求，Ollama 又只放行本地来源，两头一夹就通了个寂寞。

操作（两条路，任选其一）：

• 走扩展内置方案：进设置 → Ollama 设置 → 展开"高级 Ollama URL 配置"→ 启用自定义源 URL → 保存。这条对127.0.0.1和localhost的端口最稳。
• 走系统方案：给 Ollama 设环境变量OLLAMA_ORIGINS=*，再重启 Ollama 服务，放行所有来源。

具体步骤仓库里有专文：Ollama 连接问题排查。做完这步，你发的消息应该能正常流式返回，而不是转圈后报 403。

四、使用中的小毛病

快捷键按了没反应

现象：按Ctrl+Shift+Y想开侧边栏，纹丝不动，像是被谁抢走了。

原因：这套组合键很可能和别的扩展、输入法或系统功能撞了车。

操作：

• Chrome / Edge / Brave：打开chrome://extensions/shortcuts，找到 Page Assist，给侧边栏和 Web UI 换成别的组合键。
• Firefox：进about:addons→ 设置 → 管理扩展快捷键，同样改键。
• 改完挑个干净的网页按一下新键验证。

完整键位和改法见 快捷键文档。做完这步，按新组合键时侧边栏或 Web UI 应该立刻弹出来。

问网页却答非所问

现象：你明明在看一篇长文，模型却像个没读题的考官，答得驴唇不对马嘴。

原因：你可能停在了普通聊天模式，模型根本没拿到当前网页的内容；"与网页对话"需要单独打开。

操作：

• 在侧边栏里打开"与网页对话"开关。
• 或在输入框里按Ctrl+E，在普通模式和"当前页对话"之间切一下。
• 想关掉向量检索、直接按原文喂给模型，也可以进设置里关掉向量嵌入那项。

细节参考 与网页对话说明。做完这步，模型的回答应该能引用到你正在看的页面内容，而不是泛泛而谈。

五、通用排查思路 🔍

上面都没踩中，就按这个顺序自己走一遍，比乱试快得多：

• 先分清是"浏览器侧"还是"模型侧"的锅：扩展能加载、图标点得开，多半是模型侧；图标都点不动，先回浏览器侧。
• 把报错原文抄下来，403、连接失败、命令不存在，含义完全不同，别靠"好像不行"去猜。
• 从最小配置开始排查：默认localhost:11434、默认模型，先把最简单链路跑通，再加自定义源。
• 每改一处只改一处，改完立刻验证，别一次动五六个地方回头说不清是哪条起的作用。

做到这几条，绝大多数"玄学故障"都能被拆成一件件能确认的小事。

还解决不了时的求助路径

真卡到动不了了，按这个顺序找出口：

• 先看仓库自带的文档站（docs/目录），连接、快捷键、各功能都有对应专文。
• 再到项目的 Issues 里搜一下报错原文，十有八九有人踩过同款坑，附上浏览器版本和 Ollama 版本会更快被接住。
• 实在没头绪，就带着"我做了什么、看到了什么报错"去社区问一句，比一句"它坏了"有用一百倍。

Page Assist 的设计就是把本地模型贴进你的浏览，跑起来之后它其实很皮实——你能看到模型正常回话的那一刻，前面这些坑就都翻篇了。

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