Page Assist问题解决新手指南

费津钊Bobbie

284人浏览 · 2026-03-13 00:12:33

费津钊Bobbie · 2026-03-13 00:12:33 发布

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是一款能让你在Chrome浏览器中直接与本地AI模型交互的扩展工具，无论浏览任何网页都能随时调出侧边栏与AI对话。本指南将帮助新手用户解决从安装到使用过程中的常见问题，提供详细的安装教程、常见错误分析及实用解决方案。

安装失败问题：Bun与Ollama依赖无法正常部署如何解决？

问题定位

在执行bun install命令时终端显示command not found错误，或Ollama启动后进程立即退出，日志中出现port 11434 already in use等绑定失败提示。这类问题通常发生在首次搭建开发环境阶段，直接导致扩展无法编译或本地模型无法加载。

核心原因

Bun作为JavaScript运行时环境，其工作依赖正确配置的环境变量（Environment Variables） 和系统级的Node.js兼容层。Ollama则需要独占11434端口并依赖Docker容器化技术（若使用容器部署）。常见失败原因包括：

环境变量未包含Bun安装路径（通常为~/.bun/bin）
系统缺少glibc 2.34+等底层依赖库
端口冲突或SELinux/AppArmor安全策略限制
安装包校验失败（未通过SHA256验证）

解决方案

操作要点	原理说明
1️⃣ 执行官方安装脚本： `curl -fsSL https://bun.sh/install \| bash`	采用Bun官方提供的一键安装脚本，自动处理依赖解析和路径配置，比手动下载更可靠
2️⃣ 验证环境变量配置： `echo $PATH \| grep "$HOME/.bun/bin"`	确保Bun可执行文件路径被系统识别，否则需执行 `export PATH="$HOME/.bun/bin:$PATH"`
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或以root用户执行；Windows用户需以"管理员身份"运行PowerShell。

预防方案

环境检查清单

✅ 系统版本：确认Linux内核≥5.4，macOS≥12.0，Windows≥10 21H2
✅ 依赖库：libc6-dev、zlib1g-dev等系统库已安装
✅ 网络状态：可访问GitHub和Ollama官方仓库（无代理限制）
✅ 磁盘空间：至少10GB可用空间（含模型文件）

常见错误预警

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

扩展加载错误：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编译无错误（tsc --noEmit验证）

常见错误预警

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

快捷键冲突问题：Page Assist侧边栏无法通过快捷键调出如何解决？

问题定位

按下预设快捷键（如Alt+P）后无任何反应，或触发了系统截图、输入法切换等其他功能。此问题影响扩展使用便捷性，常见于多软件环境或非英文系统。

核心原因

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

快捷键组合已被系统或其他扩展占用
扩展未正确注册快捷键（manifest.json中commands配置错误）
Chrome快捷键设置页面存在残留配置
操作系统语言/输入法切换键干扰（如Ctrl+Shift组合）

解决方案

操作要点	原理说明
1️⃣ 访问快捷键设置页面：在Chrome地址栏输入`chrome://extensions/shortcuts`	此页面集中管理所有扩展的快捷键配置，可查看当前冲突情况
2️⃣ 定位Page Assist扩展：在列表中找到"Page Assist"扩展卡片	扩展按字母顺序排列，可使用页面搜索功能快速定位
3️⃣ 修改冲突快捷键：点击"激活扩展"对应的输入框 → 按下新组合键（如`Ctrl+Shift+Q`）	建议使用`Ctrl+Shift+[字母]`组合，这类组合在系统快捷键中使用较少
4️⃣ 测试新快捷键：打开任意网页 → 按下新设置的快捷键	成功调出侧边栏表示配置生效，失败则需尝试其他组合

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

预防方案

环境检查清单

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

常见错误预警

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

问题反馈渠道

Issue提交模板

当遇到本指南未覆盖的问题时，请按以下模板在项目仓库提交issue：

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