入口点：一个文件定义一个功能
本教程共 45 篇 · 第 7 篇 · 更新于 2026-08-13 · 约 4 分钟阅读
本节目标：理解入口点是什么，掌握单文件与目录两种写法，认识全部 13 类入口类型，学会在入口文件里声明 manifest 选项。
什么是入口点
第 04 章介绍了 entrypoints/ 目录，这一章把里面的「居民」逐个认一遍。
入口点（entrypoint）是扩展的独立功能单元。弹窗是一个入口点，后台是一个入口点，注入网页的脚本也是一个入口点。WXT 把 entrypoints/ 目录下的所有文件当作构建输入，帮你打包、生成 manifest。一个入口点由一个文件定义，或由一个目录定义；文件名（目录名）决定它的类型。
两种写法：单文件或目录
📂 entrypoints/
📄 {name}.{ext} # 单文件写法
📂 {name}/
📄 index.{ext} # 目录写法以后台入口为例，两种写法等价：
📂 entrypoints/
📄 background.ts # 写法一
📂 entrypoints/
📂 background/
📄 index.ts # 写法二目录写法的好处：配套文件可以放在 index 旁边，比如 popup 目录里的 main.ts、style.css。它们不会变成独立入口，只是弹窗的「零件」。
别把零件直接平铺进
根目录，比如
popup.ts、popup.css各放一个。WXT 会把它们各自当成一个入口点去构建，通常直接报错。需要配套文件时，用目录写法。
深层嵌套？不支持
entrypoints/ 看起来像 Nuxt 或 Next.js 的 pages/ 目录，但它不支持深层嵌套。入口点最多一层深：entrypoints/youtube.content/index.ts 合法，entrypoints/youtube/content/index.ts 不行。
遇到「一个功能一个子目录」的需求，拆成多个平级入口：
📂 entrypoints/
📂 youtube.content/ # 平级，合法
📂 youtube-injected/ # 平级，合法13 类入口类型全景
WXT 按文件名识别入口类型，一共 13 类：
| 类型 | 文件名模式（示例） | 说明 |
|---|---|---|
| 后台 background | background.ts | MV3 service worker / MV2 后台页 |
| 弹窗 popup | popup.html | 点击工具栏图标弹出 |
| 选项页 options | options.html | 扩展设置页 |
| 内容脚本 content script | content.ts、{name}.content.ts | 注入网页的脚本 |
| 侧边栏 sidepanel | sidepanel.html、{name}.sidepanel.html | 浏览器侧边栏 |
| 新标签页 newtab | newtab.html | 覆盖浏览器新标签页 |
| 开发者工具 devtools | devtools.html | 注册 DevTools 面板 |
| 书签页 bookmarks | bookmarks.html | 覆盖书签管理器 |
| 历史页 history | history.html | 覆盖历史记录页 |
| 沙盒页 sandbox | sandbox.html、{name}.sandbox.html | 受限沙盒页面（仅 Chromium） |
| 未列出页面 unlisted page | {name}.html | 打包但不注册的页面 |
| 未列出脚本 unlisted script | {name}.ts | 打包但不注册的脚本 |
| 未列出 CSS unlisted CSS | {name}.css | 打包但不注册的样式 |
前 10 类是已列出（listed）入口，会写进 manifest.json，由浏览器自动注册。后 3 类是未列出（unlisted）入口，只打包不注册，需要代码自己加载，第 13 章专门讲。
记不住全部没关系。日常 80% 的项目只用 background、popup、options、content script 四类，其余用到再查这张表。
在入口文件里声明 manifest 选项
传统开发里，入口的配置写在独立的 manifest.json。WXT 反过来：选项写在入口文件内部，构建时自动生成 manifest。
TS 入口用 defineXxx 的配置对象声明，比如内容脚本的匹配范围：
// entrypoints/content.ts
export default defineContentScript({
matches: ['*://*.wxt.dev/*'],
main() {
// ...
},
});HTML 入口用 <meta> 标签声明，比如让 MV2 弹窗使用 page_action：
<!doctype html>
<html lang="en">
<head>
<meta name="manifest.type" content="page_action" />
</head>
</html>构建时 WXT 读取这些选项，生成对应的 manifest.json（生成规则如 §25 所述）。
真实项目里的入口怎么配
mkext 是一个入口齐全的生产级项目，每个入口对应一种用户打开方式：
| 入口 | 用户如何打开 | 典型用途 |
|---|---|---|
| background | 浏览器自动管理 | 协调请求、缓存数据 |
| popup | 点击工具栏图标 | 紧凑快捷操作 |
| options | 扩展设置入口 | 完整设置页 |
| sidepanel | 浏览器侧边栏 | 边浏览边操作的常驻面板 |
| newtab | 打开新标签页 | 新标签替换页 |
| devtools + devtools-panel | 打开开发者工具 | 检查网页的专用面板 |
| tabs（未列出页面） | 代码通过 URL 打开 | 登录、帮助页 |
| google-search.content | 注入 Google 搜索结果页 | 在结果旁显示信息 |
| domain-rating.content | 注入其他网页 | 页面悬浮面板 |
选型可以记个口诀：快速操作选弹窗，复杂设置选选项页，边看边用选侧边栏，产品即首页才选新标签页，读改网页 DOM 选内容脚本，集中监听事件选后台。
不需要的入口要果断删。尤其 newtab 会改变用户习惯，删除后重新构建，检查生成的 manifest 里没有残留配置（删除步骤如 §12 所述）。
小结
- 入口点是 WXT 的核心抽象：一个文件或目录，就是一个功能。
- 13 类入口分 listed（进 manifest）与 unlisted（不进 manifest）两类，选项写在入口文件里（JS 用选项对象，HTML 用 meta 标签）。
- 入口只支持零到一层嵌套，别把文件散放在
entrypoints/根目录。