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辅助浏览的便利。

安装失败问题：Bun与Ollama依赖无法正常部署

问题速览

在执行bun install命令时终端显示command not found错误，或Ollama启动后进程立即退出，出现port 11434 already in use等绑定失败提示。

根本原因

Bun作为JavaScript运行时环境，需要正确配置环境变量路径，而Ollama需要独占11434端口。常见失败原因包括：

• 环境变量未包含Bun安装路径（通常为~/.bun/bin）
• 系统缺少必要的底层依赖库
• 端口冲突或安全策略限制
• 安装包校验失败

解决方案表格

操作步骤	命令/操作	原理说明
1. 安装Bun	curl -fsSL https://bun.sh/install | bash	使用官方一键安装脚本，自动处理依赖和路径配置
2. 验证环境变量	echo $PATH | grep "$HOME/.bun/bin"	确保系统能识别Bun可执行文件路径
3. 检查端口占用	sudo lsof -i :11434	定位占用11434端口的进程，使用kill -9 <PID>终止冲突进程
4. 启动Ollama	ollama serve --port 11435	使用备用端口验证服务可用性，排除端口冲突
5. 验证安装	bun --version && ollama --version	成功输出版本号表示基础依赖部署完成

⚠️ 权限注意：Linux/macOS用户若出现Permission denied错误，需在命令前添加sudo；Windows用户需以"管理员身份"运行PowerShell。

预防措施

环境检查清单

• ✅ 系统版本：确认Linux内核≥5.4，macOS≥12.0，Windows≥10 21H2
• ✅ 磁盘空间：至少10GB可用空间（包含模型文件）
• ✅ 网络状态：确保能访问GitHub和Ollama官方仓库
• ✅ 依赖库：确认系统库已安装最新版本

常见错误预警

• Bun安装后仍提示command not found，检查shell配置文件（.bashrc或.zshrc）是否包含Bun路径
• Ollama启动失败时，查看日志文件/var/log/ollama.log定位具体错误原因
• 国产Linux发行版建议使用Docker部署Ollama，避免系统库版本冲突

工具推荐

• asdf：版本管理工具，可同时管理Bun、Node.js等多版本运行时
• lsof：端口占用检测工具，快速定位冲突进程
• bun doctor：Bun内置诊断工具，自动检测环境配置问题

扩展加载错误：Chrome提示"无法加载扩展程序"

问题速览

在Chrome扩展页面加载解压后的扩展目录时，出现红色错误提示，可能伴随"清单文件无效"或"程序包损坏"等具体描述。

根本原因

Chrome扩展加载机制基于Manifest V3规范，要求严格的文件结构和权限声明。加载失败通常涉及：

• 未启用开发者模式导致的安全限制
• 编译过程未生成完整的build目录
• manifest.json文件存在JSON语法错误
• 扩展ID冲突或文件校验失败

解决方案表格

操作步骤	具体操作	原理说明
1. 启用开发者模式	访问chrome://extensions/ → 开启"开发者模式"开关	Chrome默认禁止加载未签名扩展，开发者模式解除此限制
2. 执行编译命令	cd /data/web/disk1/git_repo/GitHub_Trending/pa/page-assist && bun run build	生成符合Manifest V3规范的build目录，包含所有必要的编译产物
3. 验证manifest文件	使用VS Code打开build/manifest.json检查语法错误	JSON文件不允许trailing comma等语法错误，VS Code会显示红色波浪线提示
4. 正确加载扩展	点击"加载已解压的扩展程序" → 选择build目录	必须直接选择编译生成的build目录，而非项目根目录或源码目录

📌 成功验证标准：扩展图标出现在Chrome工具栏，且扩展页面显示"已启用"状态，无任何错误提示。

预防措施

环境检查清单

• ✅ 编译环境：确认bun run build命令执行无错误输出
• ✅ 文件结构：build目录包含manifest.json、service-worker.js等核心文件
• ✅ Chrome版本：≥102.0.0.0（Manifest V3最低要求）
• ✅ 代码规范：TypeScript编译无错误

常见错误预警

• 修改代码后必须重新执行bun run build，否则build目录仍为旧版本
• manifest.json中的permissions字段需严格按Chrome扩展文档声明
• Windows系统需注意文件路径长度限制，过长可能导致扩展加载失败

Ollama连接问题：CORS错误和403错误

问题现象

在Page Assist中连接Ollama时，出现直接连接错误或发送消息时出现403错误。

核心原因

这是由于CORS（跨源资源共享）限制导致的。由于Page Assist是浏览器扩展，需要通过浏览器与服务器通信，但浏览器会限制不同源之间的通信。

解决方案表格

解决方法	操作步骤	适用场景
方法一：启用自定义源URL	1. 进入Page Assist设置 2. 点击"Ollama设置"标签 3. 展开"高级Ollama URL配置" 4. 启用"启用或禁用自定义源URL"选项	Ollama运行在默认端口11434
方法二：设置环境变量	设置OLLAMA_ORIGINS=*允许任何源连接	需要永久解决CORS问题
方法三：更改Ollama端口	使用ollama serve --port 11435启动服务	端口11434被占用时

各操作系统环境变量设置

Windows系统

1. 打开开始菜单，搜索"环境变量"
2. 点击"编辑系统环境变量"
3. 点击"环境变量"按钮
4. 在"系统变量"下点击"新建"
5. 设置变量名：OLLAMA_ORIGINS，变量值：*
6. 点击确定保存
7. 重启Ollama服务

macOS系统

1. 打开终端
2. 运行命令：launchctl setenv OLLAMA_ORIGINS "*"
3. 重启Ollama服务

Linux系统

1. 打开终端
2. 运行命令：export OLLAMA_ORIGINS="*"
3. 重启Ollama服务

💡 小贴士：如果Ollama运行在不同端口，只需在Page Assist的"自定义源URL"字段中更改端口号即可。

快捷键冲突问题：Page Assist侧边栏无法调出

问题速览

按下预设快捷键（如Alt+P或Ctrl+Shift+Y）后无任何反应，或触发了系统截图、输入法切换等其他功能。

根本原因

Chrome扩展快捷键采用全局注册机制，优先级低于系统级快捷键但高于应用程序快捷键。冲突根源包括：

• 快捷键组合已被系统或其他扩展占用
• 扩展未正确注册快捷键
• Chrome快捷键设置页面存在残留配置
• 操作系统语言/输入法切换键干扰

解决方案表格

浏览器	操作步骤	注意事项
Chrome/Edge/Brave	1. 访问chrome://extensions/shortcuts 2. 找到Page Assist扩展 3. 修改"激活扩展"对应的快捷键	建议使用Ctrl+Shift+[字母]组合，这类组合在系统快捷键中使用较少
Firefox	1. 访问about:addons 2. 点击设置图标 3. 点击"管理扩展快捷键" 4. 找到Page Assist并修改快捷键	Firefox的快捷键管理界面与Chrome略有不同

推荐的快捷键组合

功能	默认快捷键	推荐替代快捷键
打开侧边栏	Ctrl+Shift+Y	Ctrl+Shift+Q
打开Web UI	Ctrl+Shift+L	Ctrl+Shift+W
新建聊天	Ctrl+Shift+O	Ctrl+Shift+N

💡 技巧：设置前可在文本编辑器中测试快捷键组合，确认不会触发其他功能后再应用到扩展设置中。

预防方案

环境检查清单

• ✅ 快捷键组合：避免使用Ctrl+C、Alt+Tab等系统级常用快捷键
• ✅ 冲突检测：设置前在快捷键设置页面搜索拟用组合，检查是否已被占用
• ✅ 多语言环境：在中文输入法状态下测试快捷键，避免Ctrl+Shift等切换键干扰

常见错误预警

• 部分系统保留快捷键无法被扩展覆盖（如F1打开帮助），需避开此类组合
• Mac用户注意区分Command和Control键，扩展快捷键设置中两者不可混用
• 远程桌面或虚拟机环境可能会拦截部分快捷键，需在物理机环境测试

项目结构概览

为了更好地理解Page Assist的工作原理，让我们简要了解项目的关键目录结构：

📁 src/                          # 主要源代码目录
├── 📁 assets/                   # 静态资源
├── 📁 components/               # React组件
├── 📁 entries/                  # 入口文件
├── 📁 libs/                     # 工具库
├── 📁 models/                   # AI模型相关
├── 📁 services/                 # 服务层
└── 📁 utils/                    # 工具函数

📁 docs/                         # 文档目录
├── 📁 features/                 # 功能文档
├── 📁 providers/                # 提供商文档
└── 📁 sidebar/                  # 侧边栏文档

核心配置文件

• wxt.config.ts：扩展构建配置文件
• package.json：项目依赖和脚本配置
• manifest.json：扩展清单文件（编译后生成）

问题反馈与社区支持

Issue提交模板

当遇到本指南未覆盖的问题时，请按以下模板提交问题：

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

获取帮助的渠道

1. 官方文档：查阅docs/目录下的详细文档
2. 项目讨论区：通过项目讨论区提问，核心开发者通常会在24小时内回复
3. 社区支持：加入项目社区获取实时帮助

📌 重要提示：提交问题前请先搜索现有问题列表，避免重复提问。涉及敏感信息（如API密钥）时，请使用脱敏处理后的日志内容。

总结

Page Assist作为一款强大的本地AI浏览器扩展，虽然安装和配置过程中可能会遇到一些问题，但通过本指南提供的解决方案，您应该能够顺利解决大多数常见问题。记住以下关键点：

• 环境检查：在开始安装前，确保系统满足最低要求
• 编译验证：每次修改代码后都要重新执行bun run build
• 快捷键管理：合理设置快捷键避免冲突
• 连接配置：正确配置Ollama的CORS设置

通过遵循这些最佳实践，您将能够充分利用Page Assist的强大功能，在浏览网页时获得AI辅助的流畅体验。

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