manifest.json 中无法妥善表达的入口或资产时,使用特殊文件夹。
在不拆分项目结构的前提下,处理额外页面、运行时注入的脚本、需要精确路径的静态资产,以及用于本地开发的附属扩展。
特殊文件夹放在哪里
特殊文件夹从项目根目录解析,而且只从那里解析。规则是:- 项目根目录是包含你的
package.json(或deno.json)的目录。 - 把
pages/、scripts/、public/与extensions/放在那个目录里,和package.json并排。 src/scripts/不是特殊文件夹。Extension.js 会忽略嵌套的特殊文件夹副本,所以放在那里的文件永远不会成为入口或被复制的资产。- 把
manifest.json移进src/不会移动项目根目录。脚手架模板把src/manifest.json和上一层的package.json一起发布,特殊文件夹属于package.json所在的层级。
package.json 也没有 deno.json 的项目。此时包含 manifest.json 的目录成为项目根目录。当那个 manifest 位于 src/ 时,src/ 就是根目录,特殊文件夹(以及 dist/)都住在 src/ 里。
模板示例
special-folders-pages

pages/ 特殊文件夹是如何工作的。
special-folders-scripts

scripts/ 特殊文件夹是如何工作的。
为什么重要
manifest 并不会直接声明很多扩展文件,比如 iframe 页面、你用chrome.scripting.executeScript 动态注入的脚本,以及静态厂商资产。开发期你还可能需要附属扩展。特殊文件夹让这些都成为构建流水线中的一等公民。
工作原理
每个特殊文件夹都有特定的角色:pages/:额外的 HTML 入口
把 pages/ 用于额外的扩展页面,例如 sandbox iframe、诊断页或内部工具。
Extension.js 会把 pages/ 中的每个 .html 文件视为一个入口,按和 manifest 声明页面相同的方式编译。
从 4.1.41 之后的版本开始,如果脚本用 getURL 指明了 pages/ 里的某个页面(例如 pages/welcome/index.html),编译后的页面也会在这个路径上提供。它的源文件不会被复制。
sandbox iframe 示例可参见 Chrome Sandbox Sample。
scripts/:独立的脚本入口
把 scripts/ 用于可执行脚本,这些脚本你会动态加载、且并不绑定到某个 HTML 页面入口。
Extension.js 会把 scripts/ 中的文件作为入口编译,使用与项目其他部分相同的扩展解析流水线。
根目录位置与输出路径
大多数scripts/ 设置问题都出在这两点。
位置。scripts/ 放在 package.json(或 deno.json)旁边,也就是项目根目录,而不是 src/ 里。即使 manifest.json 位于 src/,这条规则也成立。唯一的例外是既没有 package.json 也没有 deno.json 的项目,此时 manifest 所在目录就是根目录。参见特殊文件夹放在哪里。
**输出路径。**注入编译后的文件。scripts/foo.ts 源文件会被编译为 scripts/foo.js,所以 chrome.scripting.executeScript({ files }) 和 chrome.scripting.registerContentScripts({ js }) 必须写 .js 文件。写 .ts 路径时构建正常,但在浏览器里会 404。Extension.js 会在构建时对编译源路径字面量发出警告,并给出应使用的输出路径。
background.ts
/scripts/foo.js。Firefox 会相对于页面解析开头没有斜杠的路径。要让这个文件运行在页面自己的 world 中,参见在运行时注入脚本。
文件夹契约
你放进scripts/ 或 pages/ 的每个文件都会输出到一个可预测的路径。scripts/foo.ts 会变成 dist/<browser>/scripts/foo.js,pages/extra.html 会变成 dist/<browser>/pages/extra.html。不需要在任何地方声明该文件。像 chrome.runtime.getURL("pages/extra.html") 或 chrome.scripting.executeScript({ files: ["scripts/foo.js"] }) 这样的运行时字符串都能找到它。没有任何地方引用的文件同样会被输出,构建也不会为此打印警告。构建会把 Node.js 辅助脚本排除在外:带有 shebang、含有 Node.js import,或者路径被某个 package.json script 运行的文件。要关闭某个文件夹,在 extension.config.js 中把它的键设为 false:
extension.config.js
folders 键请参阅特殊文件夹的位置。
从 4.2.0 之后的版本起,构建只在 pages/ 与 scripts/ 中查找入口,任意深度,并跳过 node_modules 文件夹。页面以 .html 结尾。脚本以 .js、.mjs、.jsx、.mjsx、.ts、.mts、.tsx 或 .mtsx 结尾,并且必须是小写,所以 scripts/Foo.JS 不是入口。两个文件夹里的链接只要仍在项目之内就会被跟随。pages/ 或 scripts/ 里构建无法读取的文件夹会让构建以 E_FOLDER_UNREADABLE 停止,消息会点名那个文件夹。
从 4.2.0 之后的版本起,这两个文件夹也必须以小写命名。任何构建在任何磁盘上都不会读取 Pages/ 或 Scripts/ 文件夹,因此同一个项目在 macOS、Windows 和 Linux 上的构建结果相同。每个这样的文件夹都会打印一条 W_PROJECT_LAYOUT 警告,点名该文件夹并请你重命名。
从 4.2.0 之后的版本起,scripts/ 中的声明文件(.d.ts、.d.mts 或 .d.cts)永远不是入口。
两个文件对应同一个入口名
入口以它在文件夹内的路径去掉扩展名来命名。子文件夹里名为index.html 的页面代表该子文件夹。所以 pages/a.html 与 pages/a/index.html 都占用 pages/a 这个名称,scripts/a.js 与 scripts/a.ts 都占用 scripts/a。
从 4.2.0 之后的版本起,构建使用路径排序最靠后的文件:pages/a/index.html 优先于 pages/a.html,scripts/a.ts 优先于 scripts/a.js。通过文件夹内的链接到达的文件遵循同样的规则。一条 W_PROJECT_LAYOUT 警告会点名每个入口名、被使用的文件以及每个被忽略的文件。请重命名或删除被忽略的文件。
scripts/ 里的辅助模块
scripts/ 里的每个文件都会被构建成一个独立的入口。被其他文件导入的辅助模块会多输出一个没有任何东西加载的文件。从 4.1.39 之后的版本起,如果一个文件被其他文件导入,又没有任何地方按输出路径提到它,构建会为它打印一条警告。警告里给出可以直接粘贴的 exclude 值:
extension.config.js
重要契约
当你把scripts/ 中的某个条目当作类似 content script 的运行时入口使用时,请遵循 content script 初始化模式。这是 Extension.js 期望的默认导出契约,用于安全地热重载注入脚本:
- 导出一个默认函数。
- 在该函数内完成初始化。
- 可选地返回一个同步的清理函数。
scripts/ 中不允许放 Node.js 脚本
Extension.js 会用浏览器 content-script 挂载运行时包装 scripts/ 中的每个文件。如果你把一个只能在 Node.js 中运行的文件(例如 CLI 启动器或构建辅助脚本)放进去,包装器会破坏该文件。
shebang 不再位于第 1 行,且 Node 专属 API 在浏览器上下文中无法使用。
Extension.js 会检测两类 Node.js 标志,并把该文件排除在构建之外:
- 第 1 行的 shebang(
#!/usr/bin/env node)。 - 来自
node:协议的 import(例如import fs from 'node:fs')。
仅开发期的入口
名字中在扩展名之前带有.dev. 的页面或脚本是仅开发期的入口。extension dev 会像编译该文件夹中其他文件一样编译它。生产构建(extension build、extension start)则会把它排除在外:没有 HTML,没有 chunk,生成的 manifest 中也不会有任何地方点名它。
chrome.runtime.getURL("pages/player.dev.html") 能找到它。这个页面不在生产输出中,所以在会发布的代码里请给这个引用加上保护,例如放在 process.env.NODE_ENV !== "production" 之后。
- 这一约定只看文件名。名为
dev/的文件夹只是普通文件夹,pages/dev/player.html会发布。 extension build --mode development是开发期编译,所以会保留这些入口。- 不是入口的文件,例如某个页面 import 的
player.dev.css,跟随 import 它的页面。 - 要按模式或环境把额外文件复制进构建,见 extension.config.js 中的
include。
public/:仅复制的静态资产
当你需要稳定的文件路径且不希望经过打包/转换时,使用 public/。
Extension.js 会把 public/ 下的所有内容 1:1 复制到输出根目录。
从 4.1.39 之后的版本起,这次复制在每种模式下都是逐字节的。生产构建不会压缩或转换 public/ 下的文件。第三方脚本会保留它的许可证头注释、最后一个表达式,以及 sourceMappingURL 注释。你在 extension.config.js 的 include 下声明的文件也以同样的方式产出,脚本除外。除非你选择关闭,生产构建会压缩 include 进来的脚本,见构建中的额外文件。
public/ 的重要保护
不要把 manifest.json 放到 public/manifest.json。为了避免在编译过程中覆盖生成的 manifest,Extension.js 会阻止这种用法。
构建会停止。从 4.2.0 之后的版本起,构建会以 E_MANIFEST_IN_PUBLIC 停止,消息如下:
public/ 文件不会被复制。入口的文件胜出,一条 W_PROJECT_LAYOUT 警告会点名该文件。
文件夹名必须小写
从 4.2.0 之后的版本起,public 文件夹必须命名为小写的public/。Public/ 或 PUBLIC/ 文件夹会打印一条 W_PROJECT_LAYOUT 警告,请你重命名:
- 在不区分大小写的磁盘上(macOS 的默认设置),这个文件夹仍会发布。
- 此时警告会说明,其他拼写会在下一个大版本中失效。
- 在区分大小写的磁盘上(大多数 Linux 系统如此),这个文件夹里的内容都不会发布。
- 与真正的
public/文件夹并排的PUBLIC/文件夹是第二个文件夹。它里面的内容在任何磁盘上都不会发布,警告也会这样说明。
永远不会打包的文件
从 4.1.41 之后的版本起,私有文件永远不会进入构建,即使它们位于public/ 中。这包括 .env、.npmrc、.git 和 .DS_Store 等文件。引用这类文件的页面或样式表 url() 会警告一次,说明该文件未被打包。警告带有同类缺失文件所用的代码。请把内容移到另一个名字的文件中。
从 4.1.41 之后的版本起,dev 也不会提供这些文件。这包括 env 文件、Thumbs.db 和 desktop.ini 等操作系统元数据、仓库文件,以及 name~ 等编辑器备份。请求这类文件会像缺失文件一样返回 404,编辑它们也不会重新加载扩展。
extensions/:附属扩展(仅加载)
当你使用附属扩展(例如 DevTools 辅助工具)时,Extension.js 在 dev/preview/start 流程中支持把 extensions/ 文件夹作为仅加载来源。
简要说明:
- 扫描
extensions/下含manifest.json的子文件夹作为未打包的扩展根。 - 以浏览器命名的子文件夹只会为该浏览器家族加载:
extensions/chrome/用于 Chromium 目标,extensions/edge/用于 Edge,extensions/firefox/用于 Gecko 目标。根级子文件夹与你显式配置的条目在所有浏览器上都会加载。 - Extension.js 会把附属扩展和你的主扩展一起加载。
- 把这个文件夹用于加载附属扩展,而不是把它们构建进你的主产物。
--extensions CLI 参数或 extension.config.js 中的 extensions 键加载附属扩展:
chromewebstore.google.com(以及旧的 chrome.google.com/webstore 形式)、microsoftedge.microsoft.com 与 addons.mozilla.org,带不带协议或 www. 前缀都可以。下载的商店扩展会落在 extensions/<browser>/ 下,并且只为该浏览器加载。来自其他主机的链接、裸的商店 id,或既不是链接也不是路径的条目会被报告为错误,而不是被悄悄丢弃。
从 4.1.41 之后的版本起,有些伴随扩展条目只会警告,警告码为 W_COMPANION_EXTENSION_PATH。这包括项目之外的条目、不是解包扩展的文件夹,以及不存在的文件夹。浏览器打开时不会带上它。唯一的 manifest 属于 extensions/ 下某个伴随扩展的项目,仍会以 E_COMPANION_EXTENSION_PATH 被拒绝。
开发期行为(watch 模式)
在 watch 模式下,Extension.js 会监控pages/ 与 scripts/ 的文件集合变化。
在 pages/ 或 scripts/ 下添加文件,会让编译器自行重启。从 4.1.41 之后的版本开始,在那里删除或重命名文件也会这样,并且重启会移除已不存在的文件的输出。不需要手动重启。
最佳实践
- 把共享的运行时资产放在
public/:用于必须在输出中保留原文件名和路径的文件。 - 把
pages/与scripts/用于真正的入口:让 manifest 之外的执行路径保持显式。 - 让附属扩展保持隔离:把
extensions/视为本地工作流中的仅加载依赖。 - 不要把
manifest.json放进public/:Extension.js 会阻止public/manifest.json,以保护生成的扩展产物。
下一步
- 进一步了解页面重载与热模块替换 (HMR)。
- 在 Content scripts 中了解挂载契约。
- 浏览模板 以快速搭建你的下一个扩展。

