Page Assist 故障排除指南：核心问题全解析

Page Assist 是一款能够在 Chrome 浏览器中直接与本地 AI 模型交互的扩展工具，用户可随时调出侧边栏与 AI 互动。本指南为您提供 Page Assist 安装教程及常见错误的解决方案，帮助您顺利使用该工具。

一、Bun 与 Ollama 安装失败问题解决方法

问题现象

在按照教程安装依赖时，出现 Bun 命令无法使用或 Ollama 启动失败的情况，终端显示大量错误提示。

适用环境

Windows/macOS/Linux 系统

原因诊断

Bun 作为 JavaScript 运行环境，Ollama 作为本地 AI 模型管理工具，二者是 Page Assist 运行的关键。安装失败通常是由于系统环境变量（Environment Variables）配置不当或安装步骤缺失。

解决步骤

1. 安装 Bun：访问 Bun 官网，获取对应系统的安装命令并在终端执行。例如 Linux 或 macOS 系统可使用以下命令：

   curl -fsSL https://bun.sh/install | bash
   

2. 检查 Bun 路径：安装完成后重启终端，输入以下命令查看环境变量是否包含 Bun 安装路径（一般为 ~/.bun/bin）：

   echo $PATH
   

   若未包含，需手动将其添加到环境变量。
3. 安装 Ollama：前往 Ollama 官网，根据系统版本下载安装。Windows 用户需注意防火墙提示并允许相关操作。
4. 启动 Ollama 服务：安装后系统会自动启动服务，也可在终端输入以下命令手动启动：

   ollama serve
   

5. 验证安装：分别在终端输入以下命令，若能显示版本号则安装成功：

   bun --version
   ollama --version
   

预防策略

系统环境校验清单

检查项	检查方法	参考标准
系统版本	查看系统关于页面	符合 Bun 和 Ollama 最低系统要求
权限设置	Linux/macOS 使用 sudo，Windows 以管理员身份运行终端	具备安装软件的权限
网络连接	访问 Bun 和 Ollama 官网	网络通畅无代理限制
环境变量	echo $PATH 查看 Bun 路径	包含 ~/.bun/bin

二、Chrome 扩展加载失败配置教程

问题现象

在 Chrome 中加载 Page Assist 扩展时无反应，或弹出“无法加载扩展程序”错误窗口，未提示具体原因。

适用环境

Chrome 浏览器

原因诊断

常见原因包括未开启 Chrome 的开发者模式、选择了错误的加载文件夹，或扩展配置文件 manifest.json 存在错误。

解决步骤

1. 开启开发者模式：打开 Chrome 浏览器，在地址栏输入 chrome://extensions/ 进入扩展页面，开启右上角的“开发者模式”开关。
2. 生成扩展目录：若尚未编译项目，在项目根目录运行以下命令生成 build 目录：

   bun run build
   

3. 加载扩展：点击扩展页面的“加载已解压的扩展程序”按钮，选择项目的 build 目录。
4. 检查 manifest 文件：使用编辑器打开 build 目录中的 manifest.json，查看是否存在语法错误。

预防策略

系统环境校验清单

检查项	检查方法	参考标准
开发者模式	扩展页面开关状态	开关为开启状态
编译状态	查看 build 目录是否存在	包含最新编译文件
manifest 文件	检查文件名和格式	存在 manifest.json 且格式正确
扩展版本	查看 manifest 中的版本号	与项目版本一致

三、快捷键冲突问题解决方法

问题现象

按下快捷键后 Page Assist 侧边栏未调出，或触发了其他软件功能。

适用环境

所有支持 Page Assist 的操作系统

原因诊断

Chrome 扩展的快捷键为全局设置，易与系统或其他软件的快捷键冲突。

解决步骤

1. 打开快捷键设置页面：在 Chrome 地址栏输入 chrome://extensions/shortcuts。
2. 找到 Page Assist 扩展：在页面中查找并查看当前快捷键设置。
3. 修改冲突快捷键：点击快捷键输入框，按下新的快捷键组合（如 Ctrl+Shift+P），确保无冲突提示。
4. 测试新快捷键：打开新网页，按下设置的快捷键测试侧边栏是否调出。

预防策略

系统环境校验清单

检查项	检查方法	参考标准
快捷键组合	在设置页面测试	无“与其他扩展冲突”提示
常用软件快捷键	回忆常用软件的快捷键设置	避免使用相同组合
测试有效性	实际操作测试	能正常调出侧边栏

故障排查流程图

1. 遇到问题时，首先确认问题类型（安装、扩展加载或快捷键冲突）。
2. 根据问题类型查看对应章节的“问题现象”，确认是否匹配。
3. 按照“解决步骤”逐步操作，每完成一步验证是否解决。
4. 若问题仍存在，检查“系统环境校验清单”确保环境符合要求。
5. 最后参考“预防策略”避免问题再次发生。

问题反馈渠道

若按照本指南操作后问题仍未解决，可通过以下方式获取帮助：

• 项目 issue：通过项目仓库提交 issue 描述问题
• 社区支持：参与项目社区讨论，与其他用户交流解决经验

通过以上方法，您可以有效解决 Page Assist 使用过程中的常见问题，顺利体验本地 AI 模型与浏览器结合的便捷功能。