Skip to main content
按你自然的方式书写路径，让 Extension.js 把它们规范化为运行时安全的产物路径。 当你移动文件、重命名入口或改变浏览器目标时，运行时路径仍能正常工作。Extension.js 会重写 manifest 字段和扩展 API 用法中支持的路径，编译后的资产会在 dist/<browser> 内正确解析。

​
工作原理

路径解析在两处发生：
  • manifest 编译流水线：把 manifest 中声明的路径解析到输出资产。
  • JS/TS 的路径解析插件：重写传给受支持的扩展 API 的静态路径字面量(例如 runtime.getURL、tabs.update、scripting.*、action.*、sidePanel.*)。

​
支持的输入风格

Extension.js 对常见的路径输入做如下规范化： 针对 pages/ 和 scripts/ 的扩展名映射：
  • .ts、.tsx、.js、.jsx → .js
  • .njk、.nunjucks、.html → .html
  • .scss、.sass、.less、.css → .css

​
Extension.js 不会重写的情况

为了避免误判，Extension.js 会主动跳过以下输入：
  • http:// 和 https:// URL
  • data: URL
  • chrome:// URL
  • moz-extension:// URL
  • glob 模式(*、?、{}、[])
  • 构建过程无法安全解析的非静态/动态表达式

​
manifest 输出示例

假设目标浏览器是 chrome： 并不是每个 manifest 字段都映射到与源同名的目录。Extension.js 的输出路径基于面向浏览器的扩展契约，而不是你原始的编写路径。 Extension.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 阶段重视警告，它们通常意味着打包前就存在的路径不一致。

​
下一步