WXT侧边栏与开发者工具入口详解：devtools注册页与面板分离原则

侧边栏、新标签页与开发者工具入口

本教程共 45 篇 · 第 12 篇 · 更新于 2026-08-13 · 约 3 分钟阅读

WXTsidepanelnewtabdevtools浏览器扩展入口点

本节目标：认识侧边栏、新标签页、开发者工具、书签页、历史页与沙盒页六类入口，掌握 devtools 注册页与面板分离的原则。

本章入口一览

除了弹窗、选项页、后台、内容脚本，WXT 还有六类 HTML 入口。它们都是普通 HTML 页面，创建方式相同：一个文件或一个目录，差异只在名字和 manifest 效果。

侧边栏（sidepanel）固定在浏览器窗口一侧，适合边看网页边操作的场景，比如笔记、待办、AI 助手。命名：

📂 entrypoints/
   📄 sidepanel.html          # 默认侧边栏
   📄 notes.sidepanel.html    # 带名字的侧边栏

Chrome 用 side_panel API，Firefox 用 sidebar_action API，WXT 自动映射。常用配置：

<meta name="manifest.open_at_install" content="true" />
<meta name="manifest.default_icon" content="{ '16': '/icon-16.png' }" />

只要存在 sidepanel 入口，WXT 就会自动把

权限加进 manifest，不用手动声明（manifest 生成规则如 §25 所述）。

sidepanel 和 newtab 最常被商店审核关注：它们改变浏览器界面，上架时要在权限说明里写清楚用途。发布前对照 §39 的清单检查 manifest，确认没有多余的入口和权限。

侧边栏在 Chrome 114+ 支持；Firefox 的侧边栏行为与 Chrome 略有差异，跨浏览器验证时重点检查（如 §35 所述）。

newtab 入口会把浏览器的新标签页替换成你的页面：

📂 entrypoints/
   📄 newtab.html

它改变的是用户每天打开无数次的页面，影响巨大。mkext 的教程明确建议：产品不需要就别保留，删除后重新构建，确认 manifest 里没有残留覆盖配置。

接管新标签页等于抢占用户习惯。除非产品本身就是「起始页」（网址导航、小组件面板），否则不要用。

DevTools 入口分两个文件，职责必须分开：

mkext 的注册页只有几行：

// entrypoints/devtools/main.ts
void browser.devtools.panels.create(
  extensionName,
  'icons/128.png',
  'devtools-panel.html',
);

别把注册逻辑写进面板页面。面板每次打开都会执行自己的脚本，注册逻辑放里面会导致重复注册。另外

API 只在 DevTools 环境可用，别抽到 popup 等普通页面复用。

bookmarks.html 覆盖浏览器的书签管理器，history.html 覆盖历史记录页。创建方式和 newtab 一样，WXT 自动写入 manifest 的覆盖配置（MV2/MV3 字段差异见 §25）。这两个入口极少用，知道存在即可。

sandbox 入口提供一个 CSP 受限的沙盒页面，用来安全运行不可信代码（比如第三方模板引擎）：

📂 entrypoints/
   📄 sandbox.html           # 默认沙盒
   📄 editor.sandbox.html    # 带名字的沙盒

Firefox 不支持沙盒页面。跨浏览器项目需要为 Firefox 单独准备替代方案。

快速判断：边浏览边长期操作 → 侧边栏；产品即起始页 → newtab；给开发者检查网页 → DevTools；覆盖浏览器内置页 → bookmarks / history；运行不可信代码 → sandbox；都不是 → 考虑未列出页面（§13）。

注意 bookmarks / history 这类覆盖内置页的入口在部分浏览器上支持有限，跨浏览器项目先查目标浏览器的支持情况（§35）。