扩展中的 JavaScript 与 TypeScript

​

模板示例

​

javascript

npx extension@latest create my-extension --template=javascript

​

content

npx extension@latest create my-extension --template=content

​

JavaScript 能力

​

受支持的脚本入口

​

manifest.json 中的脚本声明示例

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "background": {
    "service_worker": "./scripts/background.ts"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["./scripts/content-script.ts"]
    }
  ]
}

​

开发期行为

• Content script： Extension.js 注入热模块替换（HMR）/重新挂载流程实现快速更新。
• 扩展页面： 页面脚本遵循页面 HMR 行为。
• Background/service worker： 取决于变更类型，脚本更新可能触发扩展硬重载。
• 入口列表变更： 修改 manifest 中的脚本结构可能要求重启开发服务器。

​

脚本位置与约定

• 在项目根目录使用 scripts/ 存放以脚本为中心的扩展入口。
• 使用 pages/ 存放带有自身脚本的 HTML 入口。
• 保持 manifest 引用的路径稳定；在未更新 manifest 的情况下不要移动入口文件。

​

转换与打包默认设置

• 对 JS/TS/JSX/TSX，默认使用 SWC 作为转换器。
• Extension.js 使用浏览器优先的 package.json 字段解析顺序（browser、module、main）。
• Extension.js 会以可预测方式输出入口，默认不会将代码拆分到多个输出文件中。
• 路径解析会重写受支持 API 中的静态扩展路径字面量。

​

动态 import 注意事项

• Content script 的动态 import 有运行时限制；Extension.js 会在可能时使用 loader 回退。
• Service worker 的懒加载受浏览器限制；对那些在 service worker 启动时就必须可用的代码，请优先使用静态导入。

​

最佳实践

• 让入口脚本保持精简，把功能逻辑放进共享模块。
• 对扩展 API 优先使用静态导入路径，便于路径解析安全地归一化它们。
• 避免在 content script 与 service worker 中使用不必要的动态 import。
• 在开发流程中把 manifest 中脚本列表的编辑视为结构性变更。

​

下一步

• 在 dev 更新行为 中了解更新结果。
• 在 特殊文件夹 中学习如何组织文件结构。
• 继续阅读 Background 脚本与 service worker。