dist/<browser> 内正确解析。
工作原理
路径解析在两处发生：- manifest 编译流水线：把 manifest 中声明的路径解析到输出资产。
- JS/TS 的路径解析插件：重写传给受支持的扩展 API 的静态路径字面量(例如
runtime.getURL、tabs.update、scripting.*、action.*、sidePanel.*)。
支持的输入风格
Extension.js 对常见的路径输入做如下规范化：| 输入风格 | 示例 | 规范化后的输出 |
|---|---|---|
| public 根目录(绝对路径) | /public/icons/icon.png | icons/icon.png |
| public 根目录(相对路径) | public/icons/icon.png、./public/icons/icon.png | icons/icon.png |
| 根绝对路径 | /foo/bar.js | foo/bar.js |
| 根级特殊文件夹 | /pages/popup.njk | pages/popup.html |
| 特殊文件夹 | pages/popup.html、scripts/content.tsx | pages/popup.html、scripts/content.js |
| 作者文件相对父级 | ../scripts/content.ts | scripts/content.js(解析到项目根级的特殊文件夹时) |
pages/ 和 scripts/ 的扩展名映射：
.ts、.tsx、.js、.jsx→.js.njk、.nunjucks、.html→.html.scss、.sass、.less、.css→.css
Extension.js 不会重写的情况
为了避免误判，Extension.js 会主动跳过以下输入：http://和https://URLdata:URLchrome://URLmoz-extension://URL- glob 模式(
*、?、{}、[]) - 构建过程无法安全解析的非静态/动态表达式
manifest 输出示例
假设目标浏览器是chrome：
| manifest 字段 | 输入路径 | 输出路径 |
|---|---|---|
action.default_popup | /src/popup.html | action/index.html |
background.page | /src/background.html | background/index.html |
background.service_worker | /src/background.ts | background/service_worker.js |
browser_action.default_popup | /src/popup.html | action/index.html |
chrome_url_overrides.newtab | /src/newtab.html | newtab/index.html |
content_scripts.js | /src/content_script.ts | content_scripts/content-0.js |
content_scripts.css | /src/content_style.css | content_scripts/content-0.css |
devtools_page | /src/devtools.html | devtools/index.html |
options_ui.page | /src/options.html | options/index.html |
sandbox.pages | /src/sandbox.html | sandbox/page-0.html |
side_panel.default_path | /src/sidepanel.html | sidebar/index.html |
sidebar_action.default_panel | /src/sidebar_panel.html | sidebar/index.html |
storage.managed_schema | /src/storage_schema.json | storage/managed_schema.json |
user_scripts.api_script | /src/user_script.ts | user_scripts/api_script.js |
dist/<browser> 下。
引用产物文件
对于像chrome.runtime.getURL() 这样的浏览器 API，请使用稳定的、以输出根目录为基的路径：
chrome-extension:<extension-id>/icons/icon.png
诊断与安全检查
当解析器无法把引用的路径解析到打包资产时(例如嵌套的src/pages/...，或重写后缺失的 public/ 文件)，它会给出警告。Extension.js 会在每次文件转换过程中对警告去重，以减少噪音。
重要的路径规则
- 前导
/表示扩展输出根目录，而不是文件系统根目录。 public/...和/public/...都会规范化为输出根目录中的资产。pages/与scripts/是特殊文件夹，有自己的扩展名映射规则。- Extension.js 会保留绝对的操作系统文件路径，而不会把它们当成扩展输出路径。
- 当无法安全确定最终打包路径时，Extension.js 会跳过动态表达式。
最佳实践
- 把
pages/、scripts/和public/放在项目根目录，以获得可预期的重写。 - 给扩展 API 路径尽量使用静态字面量；Extension.js 可能会跳过动态表达式。
- 把
/public/...当作输出根目录中的资产，运行时不要假设它与源码相对。 - 在
dev阶段重视警告，它们通常意味着打包前就存在的路径不一致。
下一步
- 进一步了解特殊文件夹。
- 进一步了解 web-accessible resources。