企业官网建设流程全解析

1. 从零用 Cursor 开发 Chrome 插件：为什么选 Manifest V3 加统一 API 通道

Chrome 插件开发这件事，放在两年前我会劝你先啃一遍官方文档再动手，但现在有了 Cursor 这类 AI 编辑器，整个流程可以压缩到一两个下午。这篇要聊的就是：用 Cursor 从零写一个 Chrome Extension Manifest V3 插件，核心逻辑用 JavaScript，插件内部通过统一 API 通道调用大模型能力，最终在本地加载出一个能跑的原型。

先说清楚这个插件是什么、能做什么、适合谁。它是一个浏览器侧边工具：点击插件图标弹出面板，输入或粘贴文本，点按钮就能拿到翻译或摘要结果；在网页里选中文字，也会浮出小按钮，点一下直接在浮窗里出结果。适合谁？适合想学 Manifest V3 但被 service worker、host_permissions 这些概念卡住的前端新手，也适合手上有一堆小工具想法、想快速验证的产品同学。

为什么强调 Manifest V3？因为 Chrome 已经全面转向 V3，老的 V2 写法在商店和新版本浏览器里越来越受限。V3 最大的变化是 background 从常驻页面变成了 service worker，事件驱动、随时可能被回收，这对请求逻辑的写法有直接影响。很多人第一次写 V3 插件，卡就卡在「background 里发的请求收不到回调」——本质是没理解 service worker 的生命周期。

再说 API 通道。插件要调大模型，最麻烦的不是写代码，而是 Key 管理：每个插件塞一个 Key，泄露风险高，换模型还要改代码。用 TaoToken 这类统一通道的好处是，Base URL 和 Key 固定，模型 ID 按需切换，插件里只维护一份配置。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数，配置时别把推广参数拼进去。

整篇的节奏是这样：先讲清楚项目结构和 Cursor 里的准备工作，再给可复制的 manifest.json、background、content script、popup 配置，然后演示怎么在插件里发请求、怎么本地加载验证，最后把几个高频报错挨个拆开。你跟着做，能拿到一个可运行的插件原型，而不是一堆看不懂的片段。

我试过把需求文档、UI 描述、接口说明都丢给 Cursor，让它按文件生成代码，效率比自己一行行敲高很多。但前提是你得把约束写清楚，尤其是 Manifest V3 的权限声明和 service worker 的写法，否则 AI 很容易给你生成 V2 的老代码。下面就从项目骨架开始。

2. Cursor 项目准备与 Manifest V3 插件骨架搭建

在 Cursor 里新建一个空文件夹，比如chrome-ai-helper，然后用 Cursor 打开这个文件夹。第一步不是急着写代码，而是先建一个.cursorrules文件，把项目约束写进去。这一步很关键，它决定了 Cursor 后续生成代码时会不会跑偏。我一般会写这几条：所有代码基于 Chrome Extension Manifest V3；background 使用 service worker，不用 persistent background page；请求统一走https://taotoken.net/api；每次生成或修改文件后，在 README 里追加一条变更总结。

项目目录结构建议这样组织，清晰且符合 V3 规范：

chrome-ai-helper/ ├── manifest.json ├── background.js ├── content.js ├── content.css ├── popup.html ├── popup.js ├── popup.css ├── api.js └── icons/ ├── icon16.png ├── icon48.png └── icon128.png

api.js单独抽出来放请求封装，这样 popup 和 background 都能复用，改 Base URL 或模型 ID 时只动一个文件。图标没有的话，随便找三张 PNG 放进去，尺寸对得上就行，本地加载不校验图标内容。

接下来是 manifest.json，这是 V3 插件的入口，权限、service worker、content script 都在这里声明。可以直接复制下面这份：

{ "manifest_version": 3, "name": "AI 翻译与总结助手", "version": "1.0.0", "description": "基于统一 API 通道的翻译与文本总结 Chrome 插件", "permissions": ["activeTab", "storage", "scripting"], "host_permissions": ["https://taotoken.net/*"], "background": { "service_worker": "background.js" }, "action": { "default_popup": "popup.html", "default_icon": { "16": "icons/icon16.png", "48": "icons/icon48.png", "128": "icons/icon128.png" } }, "content_scripts": [ { "matches": ["<all_urls>"], "js": ["content.js"], "css": ["content.css"], "run_at": "document_idle" } ], "icons": { "16": "icons/icon16.png", "48": "icons/icon48.png", "128": "icons/icon128.png" } }

几个点解释一下。host_permissions里必须写上https://taotoken.net/*，否则 service worker 里发请求会被跨域策略拦掉，报Failed to fetch。permissions里的activeTab让你能访问当前标签页，storage用来存配置，scripting是 V3 注入脚本用的。content_scripts的matches用<all_urls>表示所有页面都注入，实际发布时可以收窄。

在 Cursor 里，你可以直接选中 manifest.json，然后按 Cmd+K 输入「检查这份 manifest 是否符合 Manifest V3 规范，指出权限声明问题」，它会帮你过一遍。这一步能提前发现不少低级错误，比如把background.persistent写进去——V3 里这个字段已经废弃了。

骨架搭好后，先别写业务逻辑，直接去chrome://extensions打开开发者模式，点「加载已解压的扩展程序」，选这个文件夹。如果 manifest 有问题，这里会直接报错，比在代码里 debug 快得多。加载成功后你会看到插件图标出现在工具栏，点一下弹出空白页——这就说明骨架通了，可以往下填内容。

3. 可复制的 background、content script 与 API 配置

这一节是核心，把三个关键文件的代码给全，你复制进去就能用。先说 API 封装，api.js里定义 Base URL、Key 和模型 ID，这是接入统一通道的三件套：

// api.js const API_BASE_URL = "https://taotoken.net/api"; const API_KEY = "sk-你的Key"; // 替换成自己的 Key const MODEL_ID = "claude-3-5-sonnet"; // 按需切换模型 ID async function callModel(messages, maxTokens = 1024) { const resp = await fetch(`${API_BASE_URL}/v1/messages`, { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": API_KEY, "anthropic-version": "2023-06-01" }, body: JSON.stringify({ model: MODEL_ID, max_tokens: maxTokens, messages: messages }) }); if (!resp.ok) { const errText = await resp.text(); throw new Error(`API ${resp.status}: ${errText}`); } const data = await resp.json(); return data.content[0].text; }

注意这里用的是 Anthropic 风格的/v1/messages接口，请求头带x-api-key和anthropic-version。如果你用的是 OpenAI 兼容格式，改成/v1/chat/completions，请求头换成Authorization: Bearer ${API_KEY}，body 里用model和messages即可。模型 ID 按你实际要用的填，切换模型只改这一行。

然后是background.js，V3 里它是 service worker，负责接收 popup 和 content script 的消息，转发请求。这里有个坑：service worker 可能被回收，所以不要在全局变量里存状态，每次请求都从 storage 读配置。

// background.js importScripts("api.js"); chrome.runtime.onMessage.addListener((request, sender, sendResponse) => { if (request.type === "TRANSLATE" || request.type === "SUMMARIZE") { const prompt = request.type === "TRANSLATE" ? `请将以下文本翻译成中文，只输出译文：\n${request.text}` : `请用中文总结以下文本，控制在三句话内：\n${request.text}`; callModel([{ role: "user", content: prompt }]) .then((result) => sendResponse({ ok: true, data: result })) .catch((err) => sendResponse({ ok: false, error: err.message })); return true; // 关键：异步响应必须返回 true } });

return true这行是高频踩坑点。V3 的onMessage默认同步返回，如果你在回调里异步发请求，不返回 true 的话消息通道会提前关闭，popup 那边永远收不到响应，控制台报The message port closed before a response was received。

content.js负责选中文字后浮出按钮。用mouseup监听选区，动态创建按钮元素：

// content.js let floatBtn = null; document.addEventListener("mouseup", (e) => { const selection = window.getSelection().toString().trim(); if (!selection) { removeFloatBtn(); return; } showFloatBtn(e.pageX, e.pageY, selection); }); function showFloatBtn(x, y, text) { removeFloatBtn(); floatBtn = document.createElement("div"); floatBtn.className = "ai-float-btn"; floatBtn.innerHTML = `<button id="ai-translate">翻译</button><button id="ai-summarize">总结</button>`; floatBtn.style.left = `${x + 10}px`; floatBtn.style.top = `${y + 10}px`; document.body.appendChild(floatBtn); floatBtn.querySelector("#ai-translate").onclick = () => { chrome.runtime.sendMessage({ type: "TRANSLATE", text }, (res) => { alert(res.ok ? res.data : `出错：${res.error}`); }); }; floatBtn.querySelector("#ai-summarize").onclick = () => { chrome.runtime.sendMessage({ type: "SUMMARIZE", text }, (res) => { alert(res.ok ? res.data : `出错：${res.error}`); }); }; } function removeFloatBtn() { if (floatBtn) { floatBtn.remove(); floatBtn = null; } }

content.css里给.ai-float-btn加点样式，白底圆角阴影，按钮并排。popup 那边逻辑类似，popup.js里读输入框内容，发消息给 background，把结果写进结果区。popup.html 结构简单，一个 textarea、两个按钮、一个结果 div 就够。

在 Cursor 里生成这些文件时，建议一个文件一个文件来，每次生成后让它检查「是否符合 Manifest V3 的 service worker 写法」。如果它给你生成了chrome.extension.getBackgroundPage()这种 V2 的 API，直接让它改掉。

4. 本地加载验证与请求成功结果确认

代码写完后，回到chrome://extensions，点插件卡片上的刷新按钮重新加载。然后打开任意网页，选中一段文字，应该能看到浮出的翻译和总结按钮。点一下，如果配置正确，几秒内会弹出结果。

验证请求是否真的通了，有两个地方看。第一是插件页面的 service worker 控制台：在chrome://extensions找到你的插件，点「Service Worker」链接，会打开一个 DevTools 窗口，这里能看到 background 的日志和网络请求。第二是 popup 的控制台：右键插件图标选「审查弹出内容」。

如果请求成功，你在 service worker 的 Network 面板里会看到一条发往https://taotoken.net/api/v1/messages的 POST 请求，状态码 200，Response 里有模型返回的文本。这一步确认了 Base URL、Key、模型 ID 三件套都对。

popup 的完整验证流程：点插件图标，在输入框粘贴一段英文，点「翻译」，结果区应该显示中文译文。如果显示「处理中...」然后变成错误提示，去 service worker 控制台看具体报错。常见的是 401，说明 Key 不对；或者Failed to fetch，说明 host_permissions 没配对。

content script 的验证稍微麻烦一点，因为它在页面上下文里跑。选中文字后按钮没出现，先检查 content.js 有没有被注入：在页面控制台输入document.querySelector('.ai-float-btn')，如果返回 null，说明脚本没跑或者选区逻辑有问题。可以临时在 content.js 开头加console.log('content script loaded')，刷新页面看控制台有没有输出。

成功结果长这样：翻译场景下，输入「Hello world, this is a test.」返回「你好世界，这是一次测试。」；总结场景下，输入一段长文，返回三句话以内的摘要。如果返回的是英文或者格式不对，检查 prompt 里的指令是否清晰，模型对指令的遵循度跟 prompt 质量直接相关。

本地加载阶段还有个细节：每次改完代码都要点刷新，service worker 不会热重载。改 manifest.json 后必须重新加载插件，改 background.js 后点 Service Worker 的刷新，改 content.js 后刷新目标网页。这个流程走顺了，开发效率会高很多。

5. 高频报错排查：401、local proxy failed 与 reading choices

这一节把几个真实会撞上的报错拆开讲，每个都给定位方法和修复步骤。

401 Unauthorized。这是最常见的，service worker 控制台里 Response 显示{"error":{"type":"authentication_error","message":"invalid x-api-key"}}。原因就三类：Key 写错了、Key 前后有空格、请求头字段名不对。检查api.js里的API_KEY是不是完整复制，有没有多余换行。如果你用的是 OpenAI 兼容格式，请求头必须是Authorization: Bearer sk-xxx，不能再用x-api-key。改完记得刷新 service worker。

local proxy failed / Failed to fetch。这个报错通常出现在 service worker 的 Network 面板，请求根本没发出去。第一检查host_permissions里有没有https://taotoken.net/*，注意结尾的/*不能少。第二检查 Base URL 有没有拼错，https://taotoken.net/api后面接/v1/messages，别写成/api/v1/messages/v1/messages这种重复。第三，如果你本地有网络层工具在跑，可能会干扰请求，临时关掉再试。

Cannot read properties of undefined (reading 'choices')。这个报错说明你在解析响应时按 OpenAI 格式取data.choices[0].message.content，但实际返回的是 Anthropic 格式，结构是data.content[0].text。两种格式的解析方式不一样，用哪种接口就按哪种结构取。修复方法是在api.js里统一响应解析，或者干脆固定用一种接口格式，别混着写。

OAuth / 认证相关报错。如果你在插件里用了需要 OAuth 的接口，报错会提示 token 过期或 scope 不足。统一 Key 通道的好处就是绕开了 OAuth 流程，直接用 Key 认证，省掉 token 刷新逻辑。如果你确实需要 OAuth，那得单独处理授权回调，复杂度高不少，原型阶段不建议。

消息通道关闭。报错The message port closed before a response was received，前面提过，onMessage回调里异步操作必须return true。还有一种情况是 popup 已经关闭了，background 才返回响应，这时候 sendResponse 会失败，属于正常现象，加个 try-catch 忽略即可。

排查顺序建议：先看 service worker 控制台的 Network，确认请求有没有发出去；再看 Response，确认状态码和错误信息；最后看代码里的解析逻辑。三步走下来，大部分问题都能定位。Cursor 在这里也能帮上忙，把报错信息贴给它，让它分析可能原因，通常能给到靠谱的方向。

6. 从原型到可用：Cursor 协作技巧与统一通道的长期价值

原型跑通后，接下来是怎么把它打磨得更顺手。Cursor 在这个阶段的价值不是帮你写更多代码，而是帮你重构和补全。比如你可以选中content.js，让它「把浮窗改成可拖拽，并且点击页面其他区域自动关闭」，它会给你一版可用的实现。再比如让它「给所有 API 调用加上 loading 状态和错误重试」，这些细节自己写要花时间，交给它快很多。

几个协作技巧。第一，把需求拆成小任务，一次只让 Cursor 改一个文件，改完立刻在浏览器里验证，别攒一堆改动一起测。第二，善用.cursorrules里的约束，尤其是「每次修改后在 README 追加总结」这条，项目大了之后回头看变更记录很有用。第三，让它生成代码时明确指定「Manifest V3」「service worker」「不用 V2 API」，减少返工。

统一 API 通道的长期价值在于配置收敛。插件里只有api.js一个文件管 Base URL、Key、模型 ID，换模型、换 Key 都只动这一处。如果你后面要做多个插件，或者把同一套逻辑搬到别的端，这份配置可以直接复用。模型 ID 按场景选：翻译和摘要这种轻任务，用响应快的模型；如果要做长文分析，换上下文窗口大的模型，改一行就行。

再往下扩展，可以加历史记录（用chrome.storage.local存）、快捷键触发、右键菜单入口。这些在 Manifest V3 里都有对应的 API，Cursor 也熟。但建议先把当前这条链路跑稳：选中文字、发请求、拿结果、错误处理，这四步闭环了，再加功能才不会乱。

最后给个实用建议：把api.js里的 Key 换成从chrome.storage读取，而不是硬编码。这样发布前不用改代码，用户自己填 Key 就行。读取逻辑放在 service worker 启动时，或者每次请求前读一次。配合一个简单的设置页面，插件就从原型变成能给别人用的工具了。

如果你在接入过程中卡在配置上，可以去 TaoToken 的接入文档看参数说明，或者直接在模型对话里试请求格式，确认通了再写进插件。Coding Plan 适合长期做编码类 Agent 的场景，原型阶段用按量调用就够了。把这条链路走通一次，后面再写第二个、第三个插件，就是复制粘贴加微调的事。