> ## 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 契约、入口、特殊文件夹以及浏览器层面的约束。

掌握在编写真实扩展功能时真正重要的那些契约。理解 `manifest.json` 控制什么、Extension.js 会重写哪些入口。然后再决定哪些行为可以放心地自动化，哪些约束仍需要你自己处理。

## 按需开始

| 需求                                        | 先阅读这里                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------------ |
| 理解一份 manifest 如何变成各浏览器特定的产物               | [manifest.json](/docs/implementation-guide/manifest-json)                |
| 判断你的功能实际需要哪些权限                            | [权限与主机权限](/docs/implementation-guide/permissions-and-host-permissions)   |
| 在 popup、content script 与 background 之间传数据 | [消息通信](/docs/implementation-guide/messaging)                             |
| 持久化设置或缓存运行时数据                             | [存储](/docs/implementation-guide/storage)                                 |
| 构建与页面集成的功能                                | [Content script](/docs/implementation-guide/content-scripts)             |
| 构建事件驱动的扩展级逻辑                              | [Background 脚本 / service worker](/docs/implementation-guide/background)  |
| 安全地把打包资源暴露给页面                             | [Web-accessible 资源](/docs/implementation-guide/web-accessible-resources) |
| 保持输出路径可预测                                 | [可预测的路径解析](/docs/features/path-resolution)                               |

## 本节包含什么

* 单看 CLI 文档容易遗漏的编写契约。
* 由你的源码驱动、并会影响扩展加载与重载方式的运行时行为。
* 即使打包之后仍然存在的浏览器扩展架构问题，比如权限、消息通信、存储，以及 background、content script 和页面上下文之间的边界。
* 适用于手动开发或借助 AI 编码助手的实用指引。

## 重要的心智模型

Extension.js 会帮你处理编译、路径归一、manifest 重写以及开发体验。但它并不会消除浏览器扩展底层的边界：

* Content script 仍然在受限的页面上下文中运行。
* 后台 service worker 仍然有生命周期限制。
* Web-accessible 资源仍然需要显式暴露。
* 权限仍然决定扩展可以做什么。
* 消息通信和存储仍然需要显式设计。

## 适合新功能的阅读顺序

1. 先阅读 [manifest.json](/docs/implementation-guide/manifest-json)，了解你声明的扩展表面。
2. 阅读功能专属的页面，比如 [content script](/docs/implementation-guide/content-scripts) 或 [background](/docs/implementation-guide/background)。
3. 补齐支撑性内容：[权限](/docs/implementation-guide/permissions-and-host-permissions)、[消息通信](/docs/implementation-guide/messaging)、[存储](/docs/implementation-guide/storage) 与 [web-accessible 资源](/docs/implementation-guide/web-accessible-resources)。
4. 在 [可预测的路径解析](/docs/features/path-resolution) 中验证路径假设。
5. 在活动监听模式下变更入口之前，先回顾 [dev 更新行为](/docs/workflows/dev-update-behavior)。

## 下一步

* 从 [manifest.json](/docs/implementation-guide/manifest-json) 开始。
* 用 [Content script](/docs/implementation-guide/content-scripts) 构建页面集成。
* 在 [安全清单](/docs/workflows/security-checklist) 中回顾运行时边界。