Page Assist 新手常见问题解决方案

一、依赖工具安装失败如何处理？

当您尝试部署 Page Assist 时，是否遇到过终端显示红色错误信息，导致 Bun 或 Ollama 无法正常安装的情况？这两个工具是项目运行的核心组件，Bun 作为 JavaScript 运行环境提供代码执行能力，Ollama 则负责本地 AI 模型的管理与运行。安装失败通常源于系统环境配置不当或安装流程不完整。

原因剖析

1. 环境变量配置缺失：Bun 安装后未添加到系统 PATH（环境变量：操作系统中存储系统配置的键值对）
2. 系统权限不足：普通用户账户缺乏软件安装权限
3. 安装介质损坏：下载的安装包不完整或校验失败
4. 系统版本不兼容：使用的操作系统版本低于工具支持要求

解决方案

1. 安装 Bun 环境

   • 访问 Bun 官方网站获取对应系统的安装命令
   • 在终端执行安装命令（Linux/macOS 示例：curl -fsSL https://bun.sh/install | bash）
   • 关闭当前终端并重新打开，输入 bun --version 验证安装（成功会显示版本号）

2. 配置环境变量

   • 执行 echo $PATH 检查输出是否包含 ~/.bun/bin
   • 若未包含，执行 export PATH="$HOME/.bun/bin:$PATH" 添加临时路径
   • 为永久生效，将上述命令添加到 shell 配置文件（~/.bashrc 或 ~/.zshrc）

3. 安装 Ollama 服务

   • 从 Ollama 官网下载对应系统版本的安装程序
   • 执行安装文件并遵循向导完成安装
   • Windows 用户注意允许防火墙访问请求

4. 验证 Ollama 运行状态

   • 终端输入 ollama --version 检查版本信息
   • 执行 ollama serve 手动启动服务（正常运行时终端会显示服务状态信息）

预防策略

• 安装前确认系统符合最低要求（Bun 需要 glibc 2.28+，Ollama 需要支持 AVX2 指令集的 CPU）
• 使用管理员权限执行安装命令（Linux/macOS 前缀加 sudo，Windows 使用管理员终端）
• 安装完成后立即执行版本验证命令，确保工具可正常运行

二、Chrome 扩展加载失败如何解决？

在 Chrome 浏览器中加载 Page Assist 扩展时，是否遇到过"无法加载扩展程序"的错误提示，或者点击"加载已解压的扩展程序"后没有任何反应？这种情况通常与浏览器配置或项目构建状态有关。

原因剖析

1. 开发者模式未启用：Chrome 默认禁止加载未签名的扩展
2. 构建目录缺失：未生成有效的扩展文件
3. 清单文件错误：manifest.json 存在语法问题或配置错误
4. 扩展文件损坏：编译过程出错导致关键文件缺失

解决方案

1. 启用 Chrome 开发者模式

   • 在地址栏输入 chrome://extensions/ 打开扩展管理页面
   • 点击右上角"开发者模式"开关，使其变为蓝色启用状态
   • 确认页面顶部出现"加载已解压的扩展程序"等开发相关按钮

2. 构建项目文件

   • 打开终端，导航至项目根目录
   • 执行 bun run build 命令生成扩展文件
   • 等待构建完成，确认输出信息中无错误提示

3. 加载扩展程序

   • 点击"加载已解压的扩展程序"按钮
   • 导航至项目目录下的 build 文件夹并选中
   • 观察扩展列表中是否出现 Page Assist 图标

4. 检查清单文件

   • 使用代码编辑器打开 build/manifest.json
   • 检查文件是否存在语法错误（通常编辑器会用红色波浪线标记）
   • 确保 manifest 版本与 Chrome 扩展要求一致（建议使用 v3 版本）

预防策略

• 修改代码后始终重新执行 bun run build 命令
• 定期清理构建缓存（可执行 bun run clean && bun run build）
• 保持 Chrome 浏览器为最新版本，避免兼容性问题

三、快捷键无法正常工作怎么办？

设置好 Page Assist 的快捷键后，按下去却没有调出侧边栏，反而可能打开了其他程序或浏览器功能？这是典型的快捷键冲突问题，在多软件环境中很常见。

原因剖析

1. 全局快捷键冲突：与系统或其他应用的快捷键组合重复
2. 浏览器快捷键占用：Chrome 自身功能已使用该快捷键组合
3. 扩展优先级问题：其他扩展可能注册了相同的快捷键
4. 快捷键设置错误：未正确完成快捷键的设置流程

解决方案

1. 访问快捷键设置页面

   • 在 Chrome 地址栏输入 chrome://extensions/shortcuts
   • 页面加载后，向下滚动找到 Page Assist 扩展条目

2. 修改冲突快捷键

   • 点击当前快捷键旁边的铅笔图标进入编辑模式
   • 按下新的快捷键组合（推荐使用 Ctrl+Shift+字母 组合）
   • 观察输入框下方是否出现"与其他扩展冲突"的提示，如有则更换组合

3. 验证快捷键功能

   • 打开任意网页，确保浏览器窗口处于激活状态
   • 按下设置的快捷键，检查侧边栏是否正常弹出
   • 尝试在不同网页和浏览器状态下测试快捷键响应

4. 备选操作方式

   • 若快捷键始终无法正常工作，可通过 Chrome 扩展图标点击打开
   • 在扩展管理页面中，点击 Page Assist 的"详情"，设置"在工具栏中显示"

预防策略

• 选择快捷键时优先使用 Ctrl+Shift+ 或 Alt+Shift+ 前缀
• 避免使用单键或常见组合（如 Ctrl+C、Ctrl+V 等系统常用快捷键）
• 记录已设置的快捷键，定期检查是否有新安装软件导致冲突

问题诊断流程图

1. 遇到问题时，首先判断问题类型：

   • 终端显示安装错误 → 进入"依赖工具安装"流程
   • 浏览器加载扩展失败 → 进入"扩展加载"流程
   • 快捷键无响应 → 进入"快捷键设置"流程

2. 解决流程分支：

   • 安装问题：检查环境变量 → 验证权限 → 重新安装 → 版本测试
   • 扩展问题：启用开发者模式 → 检查构建目录 → 验证 manifest → 重新加载
   • 快捷键问题：访问快捷键页面 → 修改组合 → 测试响应 → 备选方案

3. 验证解决结果：

   • 安装问题：bun --version 和 ollama --version 显示版本号
   • 扩展问题：扩展图标出现在 Chrome 工具栏且可点击
   • 快捷键问题：按下设置组合键后侧边栏能正常弹出

通过以上系统化的问题解决流程，您可以快速定位并解决 Page Assist 的常见使用障碍，确保本地 AI 辅助浏览功能的顺畅运行。每个问题模块都遵循"现象识别-原因分析-分步解决-预防措施"的逻辑，帮助新手用户建立完整的问题处理思路。