> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 可预期的路径解析

> 按你自然的方式书写路径，Extension.js 会把它们规范化成运行时安全的产物路径。覆盖 manifest 字段、public 资产以及扩展 API 引用。

按你自然的方式书写路径，让 Extension.js 把它们规范化为运行时安全的产物路径。

当你移动文件、重命名入口或改变浏览器目标时，运行时路径仍能正常工作。Extension.js 会重写 manifest 字段和扩展 API 用法中支持的路径，编译后的资产会在 `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://` URL
* `data:` URL
* `chrome://` URL
* `moz-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`    |

并不是每个 manifest 字段都映射到与源同名的目录。Extension.js 的输出路径基于面向浏览器的扩展契约，而不是你原始的编写路径。

Extension.js 把所有编译产物输出到 `dist/<browser>` 下。

## 引用产物文件

对于像 `chrome.runtime.getURL()` 这样的浏览器 API，请使用稳定的、以输出根目录为基的路径：

```javascript theme={null}
const iconUrl = chrome.runtime.getURL("/icons/icon.png");
console.log(iconUrl);
```

输出：`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` 阶段重视警告，它们通常意味着打包前就存在的路径不一致。

## 下一步

* 进一步了解[特殊文件夹](/docs/features/special-folders)。
* 进一步了解 [web-accessible resources](/docs/implementation-guide/web-accessible-resources)。