Page Assist 故障排除入门指南

Page Assist 是一款能让你在 Chrome 浏览器中直接与本地 AI 模型交互的扩展工具，无论浏览何种网页，都能随时调出侧边栏进行 AI 对话。本文将以技术顾问的视角，为你系统解决从安装到使用过程中的常见问题，帮助你顺利踏上本地 AI 辅助浏览之旅。

🔍 环境配置失败：Bun 与 Ollama 部署验证

问题场景

当你在终端执行 bun run dev 命令时，屏幕显示 "command not found: bun"；或者启动 Ollama 后，Page Assist 始终提示 "无法连接本地模型服务"。这些现象通常意味着开发环境的基础组件未能正确部署。

根因解析

Bun 作为 JavaScript 运行时（替代 Node.js 的高性能环境），Ollama 作为本地 AI 模型管理工具，二者构成了 Page Assist 的技术基石。环境配置失败主要源于：

• 安装过程未完成系统环境变量（系统全局路径配置）的自动更新
• 权限不足导致的文件写入失败
• 后台服务未正确启动或被防火墙拦截

解决方案

1. Bun 环境部署

   • 执行官方安装脚本：curl -fsSL https://bun.sh/install | bash（Linux/macOS）
   • 验证安装结果：source ~/.bashrc 或重启终端后输入 bun --version
   • 手动配置路径（如自动配置失败）：

     echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
     source ~/.bashrc
     

2. Ollama 服务部署

   • 从 Ollama 官网下载对应系统版本的安装包
   • 安装完成后验证服务状态：ollama --version
   • 手动启动服务（如未自动运行）：ollama serve（后台运行可加 & 符号）

[!TIP] 对于 Linux 系统，可使用 systemctl enable ollama 设置开机自启，避免每次手动启动服务。

预防策略

• 安装前检查系统兼容性：Bun 要求 macOS 10.15+ 或 Linux 内核 5.6+
• 使用管理员权限执行安装命令：Linux/macOS 前缀加 sudo，Windows 用管理员终端
• 安装后立即验证：连续执行 bun --version 和 ollama --version 确认版本号输出

自测清单

• [ ] 终端输入 echo $PATH 能看到 .bun/bin 路径
• [ ] ollama list 命令能显示已安装的模型列表
• [ ] 无 sudo 权限时，Bun 命令仍可正常执行
• [ ] 重启终端后所有命令依然可用

🛠️ 扩展加载失败：手动验证清单

问题场景

在 Chrome 扩展页面加载解压后的扩展时，出现 "清单文件无效" 或 "无法加载扩展程序" 错误，且没有具体错误代码提示，导致无法进入下一步使用。

根因解析

扩展加载失败通常与以下因素相关：

• Chrome 开发者模式未启用，限制了未签名扩展的加载
• 项目未完成编译，缺少必要的 build 目录
• manifest.json 文件存在语法错误或不符合 Chrome 扩展规范

解决方案

1. 启用开发者模式

   • 访问 chrome://extensions/ 页面
   • 开启右上角 "开发者模式" 开关（蓝色表示已启用）
   • 勾选 "允许来自其他来源的扩展程序" 选项

2. 构建扩展文件

   • 克隆项目仓库：git clone https://gitcode.com/GitHub_Trending/pa/page-assist
   • 进入项目目录：cd page-assist
   • 安装依赖：bun install
   • 构建扩展：bun run build（成功后生成 build 目录）

3. 加载扩展程序

   • 点击 "加载已解压的扩展程序" 按钮
   • 导航至项目的 build 目录并选中
   • 如提示错误，打开 build/manifest.json 检查 JSON 语法（可使用 JSONLint 验证）

[!WARNING] 修改代码后必须重新执行 bun run build，否则扩展仍会使用旧版本文件。

预防策略

• 定期同步代码：git pull 获取最新修复
• 构建前检查依赖完整性：bun install --check
• 使用 VS Code 等编辑器实时检查 JSON 文件语法错误

自测清单

• [ ] build 目录中存在 manifest.json 文件
• [ ] 扩展加载后在扩展管理页面显示 "已启用" 状态
• [ ] 浏览器工具栏出现 Page Assist 图标
• [ ] 右键点击图标能看到扩展功能菜单

🔑 快捷键冲突：自定义组合方案

问题场景

按下 Alt+P（默认快捷键）试图调出侧边栏时，要么毫无反应，要么触发了其他应用的功能（如截图工具或输入法切换），导致无法正常使用扩展。

根因解析

Chrome 扩展的快捷键采用全局注册机制，可能与以下情况冲突：

• 系统级快捷键（如 Windows 的 Win+P 投影功能）
• 其他 Chrome 扩展的快捷键设置
• 输入法或第三方工具的全局热键

解决方案

1. 访问快捷键设置界面

   • 在 Chrome 地址栏输入 chrome://extensions/shortcuts
   • 滚动找到 "Page Assist" 扩展条目

2. 配置新快捷键组合

   • 点击快捷键输入框（显示当前绑定的按键）
   • 按下新的组合键（推荐 Ctrl+Shift+[字母] 格式）
   • 观察输入框下方提示，确认无 "冲突" 警告

3. 测试与验证

   • 打开任意网页，按下新设置的快捷键
   • 如仍无反应，尝试在无痕模式下测试（排除其他扩展干扰）
   • 检查 Page Assist 扩展是否有权限在所有网站上运行

[!TIP] 推荐使用 Ctrl+Shift+K 或 Alt+Shift+A 这类较少见的组合，降低冲突概率。

预防策略

• 选择快捷键时避开系统常用组合（如 Ctrl+S 保存、Ctrl+P 打印）
• 记录已设置的快捷键在备忘录中，避免遗忘
• 定期检查快捷键设置页面，确认无新增冲突

自测清单

• [ ] 新快捷键能在任意网页调出侧边栏
• [ ] 连续按三次快捷键不会导致浏览器异常
• [ ] 在不同网站（如百度、GitHub）均能正常触发
• [ ] 快捷键在浏览器全屏模式下依然有效

社区支持资源

当你遇到本文未覆盖的问题时，可以通过以下渠道获取帮助：

• 项目文档：查阅项目根目录下的 README.md 和 docs/ 文件夹中的详细说明
• Issue 跟踪：在项目仓库提交问题报告，描述具体现象和复现步骤
• 讨论区：参与项目的社区讨论，与其他用户交流使用经验
• 常见问题库：定期查看 docs/connection-issue.md 文档获取最新解决方案

通过以上资源，你可以获得持续的技术支持和问题解答，帮助你更好地使用 Page Assist 提升浏览体验。