# 开发运行指南

## 环境准备

克隆项目后，首次需要安装依赖：

```bash
npm install
```

`postinstall` 脚本会自动执行 `wxt prepare`，生成 `.wxt/` 类型目录。如果 VS Code 仍有 TS 报错，按 `Ctrl+Shift+P` → `TypeScript: Restart TS Server` 刷新。

## 配置

初始化完成后，编辑 `wxt.config.ts`，声明插件所需权限：

```ts
import { defineConfig } from 'wxt';

export default defineConfig({
  manifest: {
    name: '秒填鸭',
    permissions: ['storage', 'activeTab', 'scripting'],
    host_permissions: ['<all_urls>'],
  },
});
```

`permissions` 声明插件需要使用的 Chrome API，`host_permissions` 声明 content script 可运行的页面范围。

## 日常开发

```bash
npm run dev        # 开发模式，自动打开浏览器并加载插件，支持 HMR
```

`npm run dev` 启动后，WXT 会自动打开一个已加载插件的 Chrome 窗口。修改 content script、popup、background 代码后会自动热更新，无需手动去 `chrome://extensions` 刷新。

## Entrypoint 配置

每个入口文件顶部用内联声明自己的配置，例如 content script：

```ts
// entrypoints/content.ts
export default defineContentScript({
  matches: ['<all_urls>'],
  runAt: 'document_idle',
  main() {
    // 逻辑
  },
});
```

WXT 构建时会自动读取这些声明，生成 `manifest.json` 中对应字段。

## 构建

```bash
npm run build      # 生产构建
npm run zip        # 打包为可分发的 zip
```

## 跨浏览器（了解即可）

```bash
npm run dev:firefox    # Firefox 开发模式
npm run build:firefox  # Firefox 构建
```

## 目录约定

按 WXT 的约定放置文件即可，框架会自动识别角色：

| 路径 | 角色 |
|------|------|
| `entrypoints/background.ts` | Service Worker |
| `entrypoints/content.ts` | 注入网页的 content script |
| `entrypoints/popup/` | 点击图标弹出的面板 |
| `entrypoints/options/` | 插件设置页 |
| `utils/` | 工具函数，自动导入 |
| `assets/` | 静态资源 |
