3个Page Assist常见问题及解决方法：新手必读指南

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

Page Assist作为一款强大的浏览器AI助手扩展，让你能在任何网页上直接与本地AI模型对话。但在实际使用中，新手用户可能会遇到一些安装和配置问题。本文整理了三个最常见的问题及其解决方法，帮助你快速上手这个优秀的开源项目。

1. 环境依赖安装失败：Bun和Ollama无法正常部署

问题现象描述

当你尝试按照官方文档安装Page Assist时，可能会遇到以下情况：

• 执行bun install命令时提示"command not found"错误
• Ollama服务启动后立即退出，日志显示端口冲突
• 依赖包下载失败，安装过程卡住不动

根本原因分析

这些问题通常源于系统环境配置不完整。Bun作为JavaScript运行时，需要正确的环境变量路径才能被系统识别。Ollama服务默认使用11434端口，如果该端口已被其他程序占用，就会导致启动失败。此外，网络连接问题也可能影响依赖包的正常下载。

解决步骤详解

✅ 第一步：验证Bun安装状态

# 检查Bun是否已安装
bun --version

如果显示版本号，说明Bun已正确安装。如果提示"command not found"，需要重新安装：

# 使用官方脚本安装Bun
curl -fsSL https://bun.sh/install | bash

✅ 第二步：配置环境变量 安装完成后，确保Bun的路径已添加到系统环境变量中：

# 检查当前PATH是否包含Bun路径
echo $PATH | grep ".bun/bin"

# 如果未包含，添加到~/.bashrc或~/.zshrc
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

✅ 第三步：检查端口占用情况 如果Ollama无法启动，可能是端口冲突：

# 检查11434端口是否被占用
sudo lsof -i :11434

# 如果端口被占用，终止相关进程
kill -9 <进程ID>

✅ 第四步：使用备用端口启动Ollama 如果11434端口确实无法使用，可以指定其他端口：

# 使用11435端口启动Ollama
ollama serve --port 11435

预防与优化建议

• 环境检查清单：在安装前确认系统满足最低要求

  • Linux内核版本≥5.4，macOS≥12.0，Windows≥10 21H2
  • 至少10GB可用磁盘空间
  • 稳定的网络连接

• 版本管理工具：推荐使用asdf管理多个运行时版本

• 日志监控：遇到问题时查看Ollama日志：tail -f /var/log/ollama.log

2. 扩展加载失败：Chrome提示"无法加载扩展程序"

问题现象描述

在Chrome扩展管理页面加载Page Assist时，可能会遇到：

• 红色错误提示"无法加载扩展程序"
• "清单文件无效"或"程序包损坏"警告
• 扩展图标不显示在工具栏中

根本原因分析

Chrome扩展需要严格遵守Manifest V3规范，加载失败通常是因为：

1. 未启用开发者模式
2. 编译生成的build目录不完整
3. manifest.json文件存在语法错误
4. 扩展ID冲突或文件校验失败

解决步骤详解

✅ 第一步：启用开发者模式

1. 打开Chrome浏览器，访问chrome://extensions/
2. 找到右上角的"开发者模式"开关并开启

✅ 第二步：重新构建扩展 在项目目录中执行构建命令：

cd /path/to/page-assist
bun run build

如果使用npm，可以尝试：

npm run build

✅ 第三步：验证构建结果 检查build目录是否包含以下关键文件：

• manifest.json - 扩展清单文件
• background.js - 后台脚本
• 各种资源文件和图标

✅ 第四步：正确加载扩展

1. 点击"加载已解压的扩展程序"按钮
2. 选择项目中的build目录（不是项目根目录）
3. 确认扩展图标出现在工具栏

预防与优化建议

• 编译验证：每次代码修改后都要重新执行bun run build
• Chrome版本：确保使用Chrome 102+版本（支持Manifest V3）
• 文件结构检查：使用VS Code的JSON验证功能检查manifest.json语法

Page Assist的简洁图标设计，代表AI对话助手功能

3. 快捷键冲突：侧边栏无法通过快捷键调出

问题现象描述

按下预设快捷键（如Ctrl+Shift+Y）时：

• 没有任何反应
• 触发了其他程序的功能（如截图、输入法切换）
• 只在特定网页上有效

根本原因分析

快捷键冲突是常见问题，原因包括：

1. 快捷键组合已被系统或其他扩展占用
2. 扩展未正确注册快捷键命令
3. Chrome快捷键设置中存在残留配置
4. 操作系统语言或输入法干扰

解决步骤详解

✅ 第一步：访问快捷键设置页面 在Chrome地址栏输入：chrome://extensions/shortcuts

✅ 第二步：查找Page Assist扩展 在页面中找到"Page Assist"扩展卡片，查看当前快捷键配置。

✅ 第三步：修改冲突快捷键

1. 点击"激活扩展"对应的输入框
2. 按下新的快捷键组合（建议使用Ctrl+Shift+字母）
3. 保存设置

✅ 第四步：测试新快捷键 打开任意网页，按下新设置的快捷键，确认侧边栏正常弹出。

预防与优化建议

• 快捷键选择策略： | 推荐组合 | 优点 | 注意事项 | |---------|------|---------| | Ctrl+Shift+Q | 较少被占用 | 避免使用F1-F12功能键 | | Alt+Shift+P | 容易记忆 | 注意输入法切换键 | | Ctrl+Alt+S | 双手操作方便 | 部分系统可能占用 |

• 多环境测试：在不同操作系统和输入法状态下测试快捷键

• 快捷键管理工具：使用Keyboard LED Indicator等工具监控按键状态

常见问题快速排查表

问题症状	可能原因	快速解决方法
扩展图标不显示	未正确加载扩展	重新加载build目录
侧边栏无法打开	快捷键冲突	修改快捷键设置
AI模型不响应	Ollama未启动	检查Ollama服务状态
页面内容无法读取	权限设置问题	检查扩展权限设置

问题反馈模板

如果你遇到以上未覆盖的问题，请按以下模板提供信息：

问题类型：[安装/加载/功能/其他]
操作系统：[如Windows 11 22H2]
浏览器版本：[如Chrome 112.0.5615.138]
Page Assist版本：[如v1.2.0]
复现步骤：
1. [第一步操作]
2. [第二步操作]
3. [预期结果与实际结果]
错误信息：
[粘贴相关日志或截图]

通过以上步骤，大多数Page Assist的常见问题都能得到解决。记住，开源社区是你最好的支持资源，遇到问题时不妨在项目讨论区寻求帮助。祝你使用Page Assist愉快！

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