Page Assist 故障诊断手册：从环境部署到功能调优的全流程解析

问题速查索引

故障类型	关键特征	解决方案摘要
环境部署故障	终端命令无效、服务启动失败	验证Bun/Ollama安装路径与环境变量配置
扩展加载失败	Chrome提示"无法加载扩展程序"	启用开发者模式并加载正确的build目录
快捷键功能异常	按键无响应或触发其他程序	重新配置冲突快捷键组合

【环境部署故障】Bun与Ollama安装配置问题

故障表现

在终端执行bun run build命令时提示"command not found"，或运行ollama run llama2时显示"服务未启动"错误。典型场景：首次部署时按教程操作，但依赖工具始终无法正常运行。

排查流程

🔍 排查点1：运行环境兼容性

• 检查操作系统版本是否满足要求（参考下方兼容性矩阵）
• 确认系统架构是否为64位（32位系统不支持Ollama）

🔍 排查点2：安装路径验证

• 执行which bun和which ollama命令检查可执行文件位置
• 查看环境变量配置：echo $PATH（macOS/Linux）或echo %PATH%（Windows）

解决方案

标准安装流程

📌 关键点：使用官方脚本确保依赖完整性

[macOS/Linux]

# 安装Bun
curl -fsSL https://bun.sh/install | bash

# 安装Ollama
curl -fsSL https://ollama.com/install.sh | sh

[Windows]

# 安装Bun (需管理员权限)
iwr https://bun.sh/install.ps1 -useb | iex

# 安装Ollama
# 从Ollama官网下载Windows安装包并运行

前置条件：已安装curl/wget工具，网络连接正常
验证标准：bun --version和ollama --version命令返回版本号

替代方案：手动部署

当官方脚本安装失败时：

1. Bun手动安装
   下载对应系统的二进制包：

   # 解压后移动到系统路径
   mv bun-linux-x64 /usr/local/bin/bun
   chmod +x /usr/local/bin/bun
   

2. Ollama手动启动

   # 手动启动服务
   ollama serve &
   # 验证服务状态
   curl http://localhost:11434/api/tags
   

预防机制

兼容性矩阵

操作系统	支持版本	推荐Bun版本	推荐Ollama版本
Windows	10/11 64位	>=1.0.22	>=0.1.26
macOS	12.0+	>=1.0.22	>=0.1.26
Linux	Ubuntu 20.04+	>=1.0.22	>=0.1.26

环境变量持久化配置

[macOS/Linux]

# 将Bun路径添加到环境变量
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

[Windows]

# 永久添加环境变量
setx PATH "%PATH%;C:\Users\YourUser\.bun\bin"

【扩展加载故障】Chrome扩展程序加载失败

故障表现

在Chrome扩展页面加载解压后的扩展时，出现"清单文件无效"或"无法加载扩展程序"错误提示。典型场景：编译项目后首次加载扩展，或修改代码后重新加载时失败。

排查流程

🔍 排查点1：开发者模式状态

• 访问chrome://extensions/确认右上角"开发者模式"已启用（蓝色开关）

🔍 排查点2：构建文件完整性

• 检查项目根目录下是否存在build文件夹
• 确认build/manifest.json文件是否存在且格式正确

解决方案

标准加载流程

📌 关键点：确保加载正确的编译输出目录

1. 构建项目

   # 在项目根目录执行
   bun run build
   

2. 加载扩展

   • 打开Chrome扩展页面（chrome://extensions/）
   • 点击"加载已解压的扩展程序"
   • 选择项目根目录下的build文件夹

前置条件：已成功安装Bun并完成依赖安装
验证标准：扩展图标出现在Chrome工具栏，无错误提示

替代方案：修复manifest文件

当manifest.json存在格式错误时：

1. 检查JSON语法

   # 使用JSONlint验证文件格式
   bun add -g jsonlint
   jsonlint build/manifest.json
   

2. 恢复默认配置

   # 从源码重新生成manifest
   bun run generate:manifest
   

预防机制

构建流程优化

在package.json中添加预检查脚本：

"scripts": {
  "prebuild": "jsonlint src/manifest.json",
  "build": "wxt build"
}

版本控制建议

• 每次修改manifest.json后使用git diff检查变更
• 保持manifest版本与Chrome扩展商店要求同步

【功能异常故障】快捷键无响应或冲突

故障表现

按下设置的快捷键后无任何反应，或触发了系统/其他应用的功能。典型场景：使用Alt+P尝试调出侧边栏时，却打开了浏览器的打印界面。

排查流程

🔍 排查点1：快捷键配置状态

• 访问chrome://extensions/shortcuts查看Page Assist的快捷键设置
• 检查是否显示"与其他扩展冲突"警告

🔍 排查点2：全局快捷键占用

• 在系统设置中搜索"键盘快捷键"，检查是否有系统级快捷键冲突

解决方案

重新配置快捷键

📌 关键点：选择系统冲突率低的组合键

1. 访问Chrome快捷键设置页面
   在地址栏输入：chrome://extensions/shortcuts

2. 配置新快捷键

   • 找到Page Assist扩展
   • 点击快捷键输入框
   • 按下新组合键（推荐：Ctrl+Shift+Period）
   • 验证无冲突提示后点击"确定"

前置条件：Chrome浏览器版本>=90.0
验证标准：在任意网页按下新快捷键能调出Page Assist侧边栏

替代方案：通过UI菜单触发

当快捷键始终冲突时：

1. 点击Chrome工具栏的Page Assist图标
2. 在弹出菜单中选择"打开侧边栏"
3. （可选）将图标固定在工具栏：右键点击图标选择"固定"

预防机制

推荐快捷键组合

系统平台	推荐组合	冲突概率
Windows	Ctrl+Shift+P	低
macOS	Cmd+Shift+P	低
Linux	Ctrl+Shift+P	低

冲突检测工具

[Windows]

# 查看系统快捷键
Get-ItemProperty HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced | Select-Object -ExpandProperty Hotkeys

[macOS]

# 列出所有系统快捷键
defaults read com.apple.symbolichotkeys | grep -A 5 "enabled = 1"

常见误区解析

误区1：将项目源码目录直接作为扩展加载

正确认知：必须加载编译后的build目录，而非源码目录。源码需要经过Bun编译处理才能生成Chrome可识别的扩展结构。

误区2：认为Ollama安装后会自动启动

正确认知：Ollama服务需要保持运行状态，关闭终端会终止服务。生产环境应配置为系统服务自动启动：

[Linux]

# 设置Ollama开机自启
sudo systemctl enable ollama
sudo systemctl start ollama

误区3：修改代码后直接刷新扩展

正确认知：前端代码修改需重新执行bun run build，然后在扩展页面点击"刷新"按钮。不重新构建将无法应用变更。

相关问题索引

1. Page Assist如何连接远程Ollama服务？
2. 扩展加载后界面显示乱码如何解决？
3. 如何导出/导入Page Assist的聊天历史？
4. 本地模型运行时电脑风扇噪音大如何优化？
5. Page Assist支持哪些模型及如何切换？
6. 扩展提示"内存不足"时的解决方法
7. 如何在Firefox浏览器中安装Page Assist？