Page Assist 技术故障排查指南

Page Assist 技术故障排查指南

【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist

🛠️ 开发环境部署失败

问题定位

在执行项目依赖安装时，Bun - JavaScript运行环境或Ollama - 本地AI模型管理工具出现安装失败，终端显示错误代码或权限被拒绝提示。

根因剖析

开发环境部署失败主要源于三个方面：系统环境变量配置不完整导致命令无法识别、安装包校验失败或网络连接问题、以及操作系统版本不兼容。Bun和Ollama作为Page Assist的核心依赖，其安装过程对系统环境有特定要求。

解决方案

操作场景：首次部署开发环境

1. 安装Bun运行环境

   • 执行官方安装脚本：curl -fsSL https://bun.sh/install | bash
   • 手动配置环境变量：export PATH="$HOME/.bun/bin:$PATH"
   • 验证安装结果：bun --version

   「操作提示」⚠️ 注意：Linux/macOS用户若遇权限问题，需在命令前添加sudo；Windows用户需使用管理员终端执行安装。

2. 部署Ollama服务

   • 下载对应系统版本的安装包并执行安装
   • 启动服务进程：ollama serve
   • 验证服务状态：ollama --version

   「操作提示」🔍 安装后可通过ps aux | grep ollama确认服务是否在后台运行。

验证命令

# 检查Bun环境变量配置 echo $PATH | grep ".bun/bin" # 确认Ollama服务状态 systemctl status ollama # Linux系统 brew services list | grep ollama # macOS系统

经验总结

1. 安装前通过uname -a确认系统架构，避免下载错误版本的安装包
2. 网络不稳定时可使用国内镜像源加速下载
3. 开发环境建议使用Linux/macOS系统，兼容性更佳
4. 定期执行bun upgrade和ollama pull保持工具版本最新

⚠️ 扩展程序加载失败

问题定位

在Chrome浏览器扩展页面加载已解压扩展时，出现"清单文件无效"或"无法加载扩展程序"错误提示，扩展图标未正常显示。

根因剖析

扩展加载失败通常与三个因素相关：开发者模式未启用导致的权限限制、编译产物缺失或损坏、manifest.json配置文件存在语法错误或版本不兼容问题。Chrome扩展对manifest文件格式有严格要求，任何JSON语法错误都会导致加载失败。

解决方案

操作场景：本地开发调试扩展

1. 启用开发者模式

   • 访问chrome://extensions/页面
   • 开启右上角"开发者模式"开关
   • 刷新页面确认开关状态变为蓝色激活状态

2. 构建扩展文件

   • 进入项目根目录：cd /path/to/page-assist
   • 执行编译命令：bun run build
   • 确认生成build目录及内部文件结构

   「操作提示」📌 编译过程中需确保无TypeScript语法错误，可通过bun run lint提前检查代码质量。

3. 加载扩展程序

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

验证命令

# 检查编译产物完整性 ls -la build/ | grep manifest.json # 验证JSON文件格式 cat build/manifest.json | jq .

经验总结

1. 修改代码后需重新执行bun run build以更新编译产物
2. 使用jq工具检查JSON文件格式规范性
3. 扩展加载失败时可查看Chrome开发者工具的"扩展"面板获取详细错误信息
4. 保持manifest.json中的版本号与package.json同步更新

⌨️ 快捷键功能异常

问题定位

按下预设快捷键后无响应，或触发非预期功能，侧边栏未按预期弹出。

根因剖析

快捷键冲突是主要原因，Chrome扩展的全局快捷键可能与系统快捷键、其他应用程序热键或浏览器内置功能冲突。Page Assist默认快捷键可能与输入法切换、屏幕截图或窗口管理工具的快捷键重叠。

解决方案

操作场景：自定义快捷键设置

1. 访问快捷键配置页面

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

2. 修改冲突快捷键

   • 点击当前快捷键输入框使其进入编辑状态
   • 按下新的快捷键组合（建议使用Ctrl+Shift+[字母]格式）
   • 观察输入框下方是否出现冲突提示，如有则更换组合

   「操作提示」💻 推荐使用Ctrl+Shift+P作为Page Assist专属快捷键，该组合在主流应用中冲突概率较低。

3. 验证快捷键功能

   • 打开任意网页
   • 按下新设置的快捷键
   • 确认侧边栏是否正常弹出

验证命令

# 查看系统级快捷键占用情况（Linux示例） gsettings list-recursively | grep -i shortcut

经验总结

1. 避免使用单一修饰键（如仅用Ctrl或Alt）的快捷键组合
2. 记录已设置的快捷键，可在项目根目录创建shortcuts.md文档保存
3. 定期检查快捷键有效性，系统更新后可能导致新的冲突
4. 复杂快捷键可配合AutoHotkey（Windows）或Automator（macOS）创建辅助脚本

问题速查矩阵

【免费下载链接】page-assistUse your locally running AI models to assist you in your web browsing项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist