Page Assist 故障排除手册：从环境配置到功能调优的实战指南

问题导航图谱

• 环境配置类问题
  • Bun 运行环境安装失败
  • Ollama 本地模型管理工具启动异常
• 扩展加载类问题
  • Chrome 扩展程序加载失败
  • 清单文件（manifest.json）格式错误
• 功能使用类问题
  • 快捷键无响应或冲突
  • 侧边栏调用异常

一、Bun 运行环境安装失败

问题定位

在终端执行 bun run build 命令时，系统提示 "command not found: bun"，或出现 "bun: permission denied" 错误。

场景化案例：开发者小张按照教程在 Ubuntu 系统安装 Bun 后，执行构建命令时始终提示命令未找到，即使重新打开终端也无法解决。

根因剖析

Bun 作为 JavaScript 运行环境，其安装过程需要正确配置系统环境变量（系统运行时的配置参数）。Ollama 就像 AI 模型的快递员，负责把本地模型送到扩展程序手中。安装失败通常是环境变量未正确添加或权限不足导致。

底层逻辑小贴士：环境变量就像系统的"通讯录"，当输入命令时，系统会通过通讯录查找可执行文件的位置。如果通讯录没更新，就找不到新安装的程序。

解决方案

标准安装路径

▶️ 下载安装包

访问 Bun 官网下载 .msi 安装包，双击按向导完成安装

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

▶️ 验证环境变量

打开"系统属性→高级→环境变量"，检查 Path 中是否包含 C:\Program Files\Bun\bin

echo $PATH | grep "$HOME/.bun/bin"

▶️ 权限修复

sudo chown -R $USER:$USER $HOME/.bun

替代方案

▶️ 手动添加环境变量

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

▶️ 使用 NVM 管理

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
npm install -g bun

验证方法

在终端输入 bun --version，若显示类似 1.0.25 的版本号，则安装成功。

常见误区警示

1. ❌ 直接复制粘贴安装命令而未检查系统架构（32位/64位）
2. ❌ 安装后未重启终端就立即执行命令
3. ❌ 使用 sudo 权限安装但未修复目录所有者权限

经验总结

• 安装前确认系统版本符合要求（Bun 要求 macOS 10.15+ 或 Linux kernel 5.6+）
• 安装过程中注意观察终端输出，记录关键路径信息
• 定期执行 bun upgrade 保持版本最新

二、Chrome 扩展加载失败

问题定位

在 Chrome 扩展页面加载已解压的扩展程序时，出现"无法加载扩展程序"错误，或页面无任何反应。

场景化案例：开发者小李编译项目后，在 Chrome 中选择 build 目录加载扩展，却弹出"清单文件无效"的错误提示，无法继续安装。

根因剖析

扩展加载需要开启开发者模式，且必须加载编译后的 build 目录。manifest.json 就像扩展的"身份证"，记录了扩展的基本信息和权限配置。

底层逻辑小贴士：Chrome 扩展采用沙箱机制运行，manifest.json 是安全策略的重要组成部分，任何格式错误都会导致扩展被拒绝加载。

解决方案

标准流程

▶️ 开启开发者模式
在 Chrome 地址栏输入 chrome://extensions/，开启右上角"开发者模式"开关

▶️ 编译项目
在项目根目录执行：

bun run build

▶️ 加载扩展
点击"加载已解压的扩展程序"，选择项目目录下的 build 文件夹

替代方案

▶️ 检查 manifest.json
使用 VS Code 打开 build/manifest.json，检查是否有语法错误（红色波浪线标记）

▶️ 使用无痕模式测试

# Windows系统  
chrome.exe --incognito --load-extension=path\to\build

# macOS系统  
open -a "Google Chrome" --args --incognito --load-extension=/path/to/build

验证方法

扩展加载后在 Chrome 工具栏出现 Page Assist 图标，且无错误提示弹窗。

常见误区警示

1. ❌ 直接加载源代码目录而非编译后的 build 目录
2. ❌ 修改代码后未重新执行 bun run build 命令
3. ❌ 清单文件中使用了 Chrome 不支持的权限声明

经验总结

• 保持 wxt.config.ts 配置文件与 Chrome 扩展规范同步
• 每次修改代码后执行 bun run dev 进行热重载测试
• 使用 bun run lint 检查代码规范问题

三、快捷键冲突问题

问题定位

按下设置的快捷键后无任何反应，或触发了系统其他功能（如截图、输入法切换）。

场景化案例：开发者小王设置 Alt+P 作为调出侧边栏的快捷键，却发现按下后打开了系统的打印对话框，无法正常调用 Page Assist。

根因剖析

Chrome 扩展快捷键采用全局注册机制，可能与系统快捷键或其他应用程序快捷键冲突。

底层逻辑小贴士：操作系统的快捷键优先级高于应用程序，当存在冲突时，系统快捷键会优先响应。

解决方案

标准设置流程

▶️ 打开快捷键设置页面
在 Chrome 地址栏输入 chrome://extensions/shortcuts

▶️ 修改 Page Assist 快捷键
找到 Page Assist 扩展，点击快捷键输入框，按下新的组合键（推荐 Ctrl+Shift+P）

▶️ 测试快捷键
打开任意网页，按下设置的快捷键，验证侧边栏是否正常弹出

替代方案

▶️ 使用鼠标操作替代
点击 Chrome 工具栏的 Page Assist 图标调出侧边栏

▶️ 自定义快捷键组合
选择 Ctrl+Shift+[字母] 组合（如 Ctrl+Shift+K），这类组合冲突概率较低

验证方法

在任意网页按下设置的快捷键，Page Assist 侧边栏能在 1 秒内弹出。

常见误区警示

1. ❌ 使用单个功能键（如 F1-F12）作为快捷键
2. ❌ 选择与浏览器默认快捷键冲突的组合（如 Ctrl+T 新建标签页）
3. ❌ 设置后未在不同网页测试快捷键有效性

经验总结

• 优先选择 Ctrl+Shift+字母 组合，冲突概率最低
• 避免使用 Alt 键组合，容易与系统菜单冲突
• 记录已设置的快捷键，定期检查是否有新安装软件导致冲突

专家诊断流程图

1. 问题发生时首先检查系统日志
   • 查看终端输出错误信息
   • 检查 Chrome 扩展后台页面 console
2. 环境类问题排查路径
   • 验证 Bun 版本 → 检查环境变量 → 重新安装依赖
3. 扩展加载问题排查路径
   • 确认开发者模式 → 检查 build 目录 → 验证 manifest.json
4. 功能问题排查路径
   • 检查快捷键设置 → 测试无痕模式 → 重新安装扩展

高频问题自检表

问题现象	可能原因	快速解决方法
bun 命令未找到	环境变量未配置	执行 source ~/.bashrc 或重启终端
扩展加载提示清单错误	manifest.json 格式错误	运行 bun run validate 检查配置
快捷键无响应	快捷键冲突	更换为 Ctrl+Shift+P 组合
Ollama 启动失败	端口被占用	执行 ollama serve --port 11435 更换端口
侧边栏空白	资源加载失败	清除浏览器缓存后重试

进阶优化建议

1. 性能优化
   定期执行 bun run clean 清理构建缓存，使用 ollama pull llama3:8b 选择适合本地硬件的模型大小

2. 开发效率提升
   配置 bun run watch 实现代码热重载，使用 Chrome 扩展的"更新"按钮快速刷新扩展

3. 稳定性增强
   创建 .env.local 文件存储敏感配置，定期备份 ~/.ollama/models 目录保存已下载模型