从零开发一个大模型浏览器插件：准备、步骤与排错
开发一个大模型浏览器插件，核心是把浏览器扩展的页面交互能力和大模型 API 的文本生成能力接起来。
本文以 Chrome 扩展的 Manifest V3 为例，环境为 Windows 或 macOS 均可，需要你已安装 Chrome 浏览器和 Node.js（建议 18 以上），并有一个可用的大模型 API Key。
下面按准备、编码、调试、避坑的顺序展开。
先确认你要做的插件形态
大模型浏览器插件常见有三种形态：侧边栏对话、选中文本后右键解释、页面内容总结。
新手建议从「选中文本后发送到大模型并弹窗显示结果」做起，因为它不依赖复杂 UI，能快速验证 API 调用链路是否通。
开始前准备好三样东西：
- 一个空文件夹作为项目目录，例如
llm-extension - 一个可用的大模型 API 地址和 Key（以服务商文档为准）
- Chrome 浏览器，用于加载未打包扩展
搭建最小可运行项目
在项目目录下新建三个文件：manifest.json、background.js、content.js。
Manifest V3 中，网络请求建议放在 background service worker 里，避免页面上下文限制。
manifest.json 最小配置如下：
{
"manifest_version": 3,
"name": "LLM 划词助手",
"version": "1.0",
"permissions": ["contextMenus", "scripting", "activeTab"],
"host_permissions": ["https://api.example.com/*"],
"background": { "service_worker": "background.js" },
"content_scripts": [
{ "matches": [""], "js": ["content.js"] }
]
} 注意把 host_permissions 换成你实际调用的大模型 API 域名，否则请求会被浏览器拦截。
background.js 负责创建右键菜单并调用 API：
chrome.runtime.onInstalled.addListener(() => {
chrome.contextMenus.create({
id: "explain",
title: "用大模型解释选中内容",
contexts: ["selection"]
});
});
chrome.contextMenus.onClicked.addListener(async (info, tab) => {
if (info.menuItemId !== "explain" || !info.selectionText) return;
const res = await fetch("https://api.example.com/v1/chat/completions", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer 你的API_KEY"
},
body: JSON.stringify({
model: "你的模型名",
messages: [{ role: "user", content: "请解释：" + info.selectionText }]
})
});
const data = await res.json();
const reply = data.choices?.[0]?.message?.content || "请求失败";
chrome.scripting.executeScript({
target: { tabId: tab.id },
func: (text) => alert(text),
args: [reply]
});
});content.js 可以先留空，仅用于满足 manifest 中的声明；
后续要做页面内浮层时再扩展。
加载调试与效果验证
打开 Chrome，地址栏输入 chrome://extensions/，开启右上角「开发者模式」，点击「加载已解压的扩展程序」，选择 llm-extension 文件夹。
加载成功后，在任意网页选中一段文字，右键应出现「用大模型解释选中内容」。
点击后如果弹出回复内容，说明链路已通。
如果没有任何反应，按 F12 打开开发者工具，在「扩展程序」页找到你的插件，点击「Service Worker」链接查看后台报错。
常见检查项：
- 右键菜单没出现：确认
contextMenus权限已声明，并重新加载扩展 - 请求 401 或 403：检查 API Key 是否有效、请求头格式是否正确
- 请求被拦截：核对
host_permissions是否包含实际 API 域名 - 弹窗无内容：在 background 控制台打印
data，确认返回结构是否符合预期
新手最容易踩的几个坑
第一，把 API Key 直接写在前端代码里。
浏览器扩展的代码对用户可见，正式发布前应通过自己的后端中转请求，避免 Key 泄露。
第二，Manifest V3 的 service worker 会休眠，不要在全局变量里存关键状态，需要时从 chrome.storage 读取。
第三，host_permissions 漏写会导致 fetch 静默失败，务必对照 API 文档补全。
第四，跨域和内容安全策略问题优先看 background 控制台，而不是页面控制台。
常见疑问
插件必须用 Node.js 吗？ 不一定。
纯手写 HTML、JS、JSON 也能开发扩展，Node.js 主要用于打包、构建和本地 mock 服务。
大模型 API 调用放在 content script 里可以吗？ 技术上部分场景可行，但受页面 CSP 和跨域限制影响大，建议统一放 background 中处理。
如何验证插件是否真的调用了大模型？ 在 background 的 fetch 前后加 console.log，并在服务商控制台查看请求记录，两处能对上即可确认。
到这里，一个可运行的大模型浏览器插件原型就完成了。
后续再按需增加侧边栏 UI、流式输出和历史记录，建议每加一个功能就重新加载扩展并复查 background 控制台，排错成本最低。
