WXT浏览器插件开发中文教程(3)----WXT全部入口项详解

倔强青铜三2025-03-24 22:36

前言

大家好，我是倔强青铜三 。是一名热情的软件工程师，我热衷于分享和传播IT技术，致力于通过我的知识和技能推动技术交流与创新，欢迎关注我，微信公众号：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！

入口项

WXT 在捆绑扩展时，将 entrypoints/ 目录中的文件作为输入。这些文件可以是 HTML、JS、CSS 或 Vite 支持的任何变体（如 Pug、TS、JSX、SCSS 等）。

以下是一个入口项示例：

html 复制代码 
📂 entrypoints/
   📂 popup/
      📄 index.html
      📄 main.ts
      📄 style.css
   📄 background.ts
   📄 content.ts

已列出与未列出

对于网络扩展，有两种类型的入口项：

  • 已列出 ：在 manifest.json 中引用
  • 未列出 ：不在 manifest.json 中引用

在 WXT 的其余文档中，已列出的入口项按名称引用。例如：

  • 弹出窗口
  • 选项
  • 背景
  • 内容脚本
  • 等等

一些"未列出"的入口项示例：

  • 扩展安装时显示的欢迎页面
  • 内容脚本注入到页面主世界中的 JS 文件

提示

无论入口项是已列出还是未列出，它都会被捆绑到扩展中，并在运行时可用。

添加入口项

入口项可以定义为单个文件或包含 index 文件的目录。

单个文件目录

html 复制代码 
📂 entrypoints/
   📄 background.ts
html 复制代码 
📂 entrypoints/
   📂 background/
      📄 index.ts

入口项的名称决定其类型，即已列出与未列出。在此示例中，"background" 是 背景入口项 的名称。

有关已列出入口项的完整列表及其文件名模式，请参阅 入口项类型 部分。

定义清单选项

大多数已列出的入口点需要添加到 manifest.json 的选项。但使用 WXT 时，无需在单独的文件中定义这些选项，而是 在入口项文件本身内定义这些选项。

例如，以下是如何为内容脚本定义 matches：

entrypoints/content.ts

ts 复制代码 
export default defineContentScript({
  matches: ['*://*.wxt.dev/*'],
  main() {
    // ...
  },
});

对于 HTML 入口项，选项配置为 <meta> 标签。例如，要为 MV2 弹出窗口使用 page_action：

html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta name="manifest.type" content="page_action" />
  </head>
</html>

请参阅 入口项类型 部分，以获取可在每个入口项内配置的选项列表及其定义方法。

构建扩展时，WXT 会查看入口项中定义的选项，并据此生成清单。

入口项类型

background脚本

Chrome 文档 • Firefox 文档

对于 MV2，background脚本作为脚本添加到后台页面。对于 MV3，background脚本变为服务工作线程。

文件名 输出路径
entrypoints/background.[jt]s /background.js
entrypoints/background/index.[jt]s /background.js

最小化并带有清单选项

ts 复制代码 
export default defineBackground(() => {
  // 背景加载时执行
});
ts 复制代码 
export default defineBackground({
  // 设置清单选项
  persistent: undefined | true | false,
  type: undefined | 'module',
  // 如果背景应从某些构建中移除，则设置 include/exclude
  include: undefined | string[],
  exclude: undefined | string[],
  main() {
    // 背景加载时执行，不能是异步的
  },
});

书签

Chrome 文档 • Firefox 文档

文件名 输出路径
entrypoints/bookmarks.html /bookmarks.html
entrypoints/bookmarks/index.html /bookmarks.html
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>标题</title>
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

内容脚本

Chrome 文档 • Firefox 文档

有关在内容脚本中创建 UI 和包含 CSS 的更多信息，请参阅 内容脚本 UI。

文件名 输出路径
entrypoints/content.[jt]sx? /content-scripts/content.js
entrypoints/content/index.[jt]sx? /content-scripts/content.js
entrypoints/<name>.content.[jt]sx? /content-scripts/<name>.js
entrypoints/<name>.content/index.[jt]sx? /content-scripts/<name>.js
ts 复制代码 
export default defineContentScript({
  // 设置清单选项
  matches: string[],
  excludeMatches: undefined | [],
  includeGlobs: undefined | [],
  excludeGlobs: undefined | [],
  allFrames: undefined | true | false,
  runAt: undefined | 'document_start' | 'document_end' | 'document_idle',
  matchAboutBlank: undefined | true | false,
  matchOriginAsFallback: undefined | true | false,
  world: undefined | 'ISOLATED' | 'MAIN',
  // 如果背景应从某些构建中移除，则设置 include/exclude
  include: undefined | string[],
  exclude: undefined | string[],
  // 配置 CSS 如何注入到页面
  cssInjectionMode: undefined | "manifest" | "manual" | "ui",
  // 配置内容脚本的注册方式
  registration: undefined | "manifest" | "runtime",
  main(ctx: ContentScriptContext) {
    // 内容脚本加载时执行，可以是异步的
  },
});

开发者工具

Chrome 文档 • Firefox 文档

请遵循 开发者工具示例 以添加不同的面板和窗格。

文件名 输出路径
entrypoints/devtools.html /devtools.html
entrypoints/devtools/index.html /devtools.html
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

历史记录

Chrome 文档 • Firefox 文档

文件名 输出路径
entrypoints/history.html /history.html
entrypoints/history/index.html /history.html
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>标题</title>
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

新标签页

Chrome 文档 • Firefox 文档

文件名 输出路径
entrypoints/newtab.html /newtab.html
entrypoints/newtab/index.html /newtab.html
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>标题</title>
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

选项

Chrome 文档 • Firefox 文档

文件名 输出路径
entrypoints/options.html /options.html
entrypoints/options/index.html /options.html
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>选项标题</title>
    <!-- 自定义清单选项 -->
    <meta name="manifest.open_in_tab" content="true|false" />
    <meta name="manifest.chrome_style" content="true|false" />
    <meta name="manifest.browser_style" content="true|false" />
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

弹出窗口

Chrome 文档 • Firefox 文档

文件名 输出路径
entrypoints/popup.html /popup.html
entrypoints/popup/index.html /popup.html
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- 在清单中设置 `action.default_title` -->
    <title>默认弹出窗口标题</title>
    <!-- 自定义清单选项 -->
    <meta
      name="manifest.default_icon"
      content="{
        16: '/icon-16.png',
        24: '/icon-24.png',
        ...
      }"
    />
    <meta name="manifest.type" content="page_action|browser_action" />
    <meta name="manifest.browser_style" content="true|false" />
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

沙盒

Chrome 文档

仅限 Chromium

Firefox 不支持沙盒页面。

文件名 输出路径
entrypoints/sandbox.html /sandbox.html
entrypoints/sandbox/index.html /sandbox.html
entrypoints/<name>.sandbox.html /<name>.html
entrypoints/<name>.sandbox/index.html /<name>.html
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>标题</title>
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

侧边面板

Chrome 文档 • Firefox 文档

在 Chrome 中，侧边面板使用 side_panel API，而在 Firefox 中则使用 sidebar_action API。

文件名 输出路径
entrypoints/sidepanel.html /sidepanel.html
entrypoints/sidepanel/index.html /sidepanel.html
entrypoints/<name>.sidepanel.html ``/<name>.html```
entrypoints/<name>.sidepanel/index.html ``/<name>.html```
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>默认侧边面板标题</title>
    <!-- 自定义清单选项 -->
    <meta
      name="manifest.default_icon"
      content="{
        16: '/icon-16.png',
        24: '/icon-24.png',
        ...
      }"
    />
    <meta name="manifest.open_at_install" content="true|false" />
    <meta name="manifest.browser_style" content="true|false" />
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

[未列出的 CSS](#未列出的 CSS "#unlisted-css")

按照 Vite 的指南设置首选的预处理器：vitejs.dev/guide/featu...

CSS 入口点总是未列出的。要将 CSS 添加到内容脚本，请参阅 内容脚本 文档。

文件名 输出路径
`entrypoints/<name>.(css scss
`entrypoints/<name>/index.(css scss
`entrypoints/content.(css scss
`entrypoints/content/index.(css scss
`entrypoints/<name>.content.(css scss
`entrypoints/<name>.content/index.(css scss
css 复制代码 
body {
  /* ... */
}

未列出的页面

文件名 输出路径
entrypoints/<name>.html /<name>.html
entrypoints/<name>/index.html /<name>.html
html 复制代码 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>标题</title>
    <!-- 如果页面应从某些构建中移除，则设置 include/exclude -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
  </head>
  <body>
    <!-- ... -->
  </body>
</html>

页面可通过 /<name>.html 访问：

ts 复制代码 
const url = browser.runtime.getURL('/<name>.html');
console.log(url); // "chrome-extension://<id>/<name>.html"

未列出的脚本

文件名 输出路径
entrypoints/<name>.[jt]sx? /<name>.js
entrypoints/<name>/index.[jt]sx? /<name>.js

最小化并带有选项

ts 复制代码 
export default defineUnlistedScript(() => {
  // 脚本加载时执行
});
ts 复制代码 
export default defineUnlistedScript({
  // 如果脚本应从某些构建中移除，则设置 include/exclude
  include: undefined | string[],
  exclude: undefined | string[],
  main() {
    // 脚本加载时执行
  },
});

脚本可从 /<name>.js 访问：

ts 复制代码 
const url = browser.runtime.getURL('/<name>.js');
console.log(url); // "chrome-extension://<id>/<name>.js"

你需要负责在需要的地方加载/运行这些脚本。如果需要，别忘了将脚本及相关资源添加到 web_accessible_resources。

最后感谢阅读！欢迎关注我，微信公众号 ：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！

相关推荐
知识分享小能手5 分钟前
CSS3学习教程，从入门到精通，CSS3 定位布局页面知识点及案例代码（18）
前端·javascript·css·学习·html·css3·html5
Python私教18 分钟前
Vue 在现代 Web 开发中的优势
前端·javascript·vue.js
Front_Yue26 分钟前
Unity 与 JavaScript 的通信交互：实现跨平台的双向通信
javascript·3d·unity
fridayCodeFly26 分钟前
＜KeepAlive＞和＜keep-alive＞有什么区别
前端·javascript·vue.js
hikktn31 分钟前
【开源宝藏】30天学会CSS - DAY8 第八课 跳动的爱心动画
前端·css·开源
南蓝31 分钟前
【node】如何用 pm2 管理 node 项目
前端
寻梦人1213833 分钟前
Vite管理的Vue3项目中monaco editer的使用以及组件封装
前端·javascript·vue.js·vscode
瓶子丶33 分钟前
企业微信通讯录效果？拿捏！！！
vue.js·uni-app
头发尚存的猿小二44 分钟前
Linux--环境变量
前端·javascript·chrome
uuuuu17116441 小时前
HTML5 canvas圆形泡泡动画背景特效
前端·html·html5
热门推荐
01RAG 实践- Ollama+RagFlow 部署本地知识库02如何在WPS和Word/Excel中直接使用DeepSeek功能03DeepSeek各版本说明与优缺点分析04本地化部署AI知识库：基于Ollama+DeepSeek+AnythingLLM保姆级教程05本地部署DeepSeek教程（Mac版本）06从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑07苍穹外卖面试总结08FreeCAD傻瓜教程之创建参数化几何图形-螺旋体、平面、球体、椭球体、圆柱体、圆锥体、棱柱、椭圆09DeepSeek R1本地化部署 Ollama + Chatbox 打造最强 AI 工具10LLaMA-Factory DeepSeek-R1 模型 微调基础教程