Page Assist 实战诊断：开源工具排障手记

2026-03-13 04:15:58作者：虞亚竹Luna

在使用 Page Assist 这款能让你在 Chrome 浏览器里直接和本地 AI 模型聊天的扩展工具时，可能会遇到各种问题。本文将以"问题定位→根源解析→阶梯式解决方案→长效预防"的四段式结构，为你提供专业易懂的开源工具排障指南，帮助你顺利解决从初始化到使用过程中的常见故障。

初始化阶段：环境搭建故障

问题定位：Bun 和 Ollama 安装失败

症状自检清单

[ ] 运行 Bun 命令时提示"command not found"
[ ] Ollama 启动后无响应或终端显示红色错误信息
[ ] 执行安装命令后未生成预期的程序文件

根源解析

Bun 作为 JavaScript 运行环境（就像专门为 JavaScript 程序准备的"厨房"），Ollama 作为本地 AI 模型的"管家"，二者是 Page Assist 正常运行的关键。安装失败通常是系统环境变量（系统路径导航图）配置不当或安装步骤遗漏导致。

场景类比说明

这就像安装厨房设备，Bun 是烤箱，Ollama 是冰箱，只有两者都正确安装并连接到厨房电路（环境变量），才能正常烹饪（运行程序）。

阶梯式解决方案

应急处理

安装 Bun：前往 Bun 官网获取对应系统的安装命令，在终端执行。
- 操作指令：输入安装命令并回车
- 预期结果：终端显示安装进度，最后提示安装成功
安装 Ollama：访问 Ollama 官网，选择合适系统版本下载安装。
- 操作指令：运行安装程序并按提示完成安装
- 预期结果：安装完成后 Ollama 服务自动启动

深度优化

检查 Bun 路径：重启终端后输入 echo $PATH，查看输出是否包含 Bun 安装路径（一般是 ~/.bun/bin）。
- 操作指令：在终端输入命令并回车
- 预期结果：输出内容中能找到 Bun 的安装路径
手动配置环境变量：若未找到 Bun 路径，需将其添加到环境变量。
- 操作指令：编辑环境变量配置文件，添加路径后保存
- 预期结果：再次检查路径时能看到新增的 Bun 路径
手动启动 Ollama 服务：在终端输入 ollama serve 启动服务。
- 操作指令：输入命令并回车
- 预期结果：终端显示服务启动信息，无错误提示
验证安装：分别输入 bun --version 和 ollama --version。
- 操作指令：输入命令并回车
- 预期结果：显示相应的版本号，无错误提示

#排障技巧：安装过程中遇到权限问题，Linux/macOS 用户可在命令前加 sudo，Windows 用户用管理员身份打开终端。

长效预防

安装前确认系统版本是否符合要求，避免因系统过旧导致不兼容
安装完成后立即验证，及时发现并解决问题
记录安装过程中的关键步骤和配置，便于后续排查

经验值获取

学会检查环境变量配置，掌握程序路径验证方法
了解软件安装的基本流程和常见问题处理方式
培养操作后验证结果的良好习惯

配置阶段：扩展加载故障

问题定位：Chrome 加载扩展失败

症状自检清单

[ ] 点击"加载已解压的扩展程序"后无反应
[ ] 弹出错误窗口提示"无法加载扩展程序"
[ ] 扩展页面显示"清单文件无效"

根源解析

加载扩展失败主要原因是未开启 Chrome 开发者模式，或选择了错误的加载目录，也可能是扩展配置文件 manifest.json 存在语法错误。

场景类比说明

这好比给电脑安装软件，需要开启允许安装非官方软件的权限（开发者模式），选择正确的安装包（build 目录），并且安装包不能损坏（manifest.json 正确）。

阶梯式解决方案

应急处理

开启开发者模式：打开 Chrome 浏览器，在地址栏输入 chrome://extensions/ 进入扩展页面，开启右上角"开发者模式"开关。
- 操作指令：点击开关按钮，使其变为蓝色
- 预期结果：页面显示"加载已解压的扩展程序"等开发者选项
生成 build 目录：在项目根目录运行 bun run build 命令。
- 操作指令：在终端切换到项目目录，输入命令并回车
- 预期结果：终端显示编译过程，完成后生成 build 目录
加载扩展：点击"加载已解压的扩展程序"按钮，选择项目的 build 目录。
- 操作指令：在文件选择窗口中找到并选中 build 目录
- 预期结果：扩展成功加载，在扩展列表中显示

深度优化

检查 manifest 文件：用编辑器打开 build 目录中的 manifest.json 文件，查看是否有语法错误。
- 操作指令：用 VS Code 等编辑器打开文件
- 预期结果：文件中无红色波浪线等错误提示
验证文件完整性：确认 build 目录中包含所有必要的扩展文件。
- 操作指令：浏览 build 目录中的文件列表
- 预期结果：包含 manifest.json 及其他扩展所需文件

#排障技巧：如果提示"清单文件无效"，可参考 Chrome 开发者文档中关于 manifest 文件的格式要求进行修改。

长效预防

修改代码后重新运行 bun run build，确保 build 目录文件最新
加载扩展前检查 build 目录中是否存在 manifest.json 文件
定期清理浏览器缓存，避免旧文件干扰

经验值获取

掌握 Chrome 扩展开发模式的基本操作
了解扩展配置文件的重要性和基本格式要求
学会编译生成扩展文件的方法

使用阶段：功能异常故障

问题定位：快捷键无响应或冲突

症状自检清单

[ ] 按下快捷键后 Page Assist 侧边栏未弹出
[ ] 按下快捷键后打开了其他程序或功能
[ ] 快捷键设置页面提示"与其他扩展冲突"

根源解析

Chrome 扩展的快捷键是全局的，容易与系统或其他软件的快捷键冲突。就像不同的人抢用同一个电话号码，导致无法接通正确的人。

场景类比说明

这就像办公室里的对讲机频道冲突，多个部门使用同一个频道时，说话会相互干扰，需要各自调整到不同的频道才能正常通讯。

阶梯式解决方案

应急处理

打开快捷键设置页面：在 Chrome 地址栏输入 chrome://extensions/shortcuts。
- 操作指令：在地址栏输入地址并回车
- 预期结果：进入扩展快捷键设置页面
修改冲突快捷键：找到 Page Assist 扩展，点击快捷键输入框，按下新的快捷键组合。
- 操作指令：点击输入框，按下新的组合键（如 Ctrl+Shift+P）
- 预期结果：输入框显示新的快捷键组合，无冲突提示

深度优化

选择合适的快捷键组合：优先使用 Ctrl+Shift+字母 或 Alt+Shift+字母 组合。
- 操作指令：尝试不同的组合键，观察是否有冲突提示
- 预期结果：找到无冲突的快捷键组合
测试新快捷键：设置完成后，在新网页中测试快捷键是否生效。
- 操作指令：打开新网页，按下设置的快捷键
- 预期结果：Page Assist 侧边栏成功弹出

#排障技巧：设置快捷键时，避开常用软件的快捷键组合，减少冲突概率。

长效预防

选择快捷键时，考虑常用软件的快捷键设置，避免冲突
记录设置的快捷键，便于记忆和后续调整
定期检查快捷键设置，确保没有新的冲突产生

经验值获取

掌握 Chrome 扩展快捷键的设置方法
学会解决快捷键冲突的基本技巧
培养设置和使用快捷键的良好习惯

常见问题速查表

问题类型	关键解决步骤
初始化故障	1. 官网命令安装 Bun 和 Ollama 2. 验证 `bun --version` 和 `ollama --version` 能运行
配置故障	1. 开启 Chrome 开发者模式 2. 加载项目的 build 目录 3. 检查 manifest.json 格式
使用故障	1. 进入 `chrome://extensions/shortcuts` 修改快捷键 2. 选择 `Ctrl+Shift+字母` 类组合