项目结构：代码该放哪儿

默认结构：扁平但分工明确

WXT 遵循严格的项目结构，默认是扁平布局：

项目根目录/
├── .output/        # 构建产物目录
├── .wxt/           # WXT 生成的 TS 配置（勿手改）
├── assets/         # 需要 WXT/Vite 处理的资源（CSS、图片）
├── components/     # UI 组件（默认自动导入）
├── composables/    # Vue 组合式函数（默认自动导入）
├── entrypoints/    # 入口点，打包进扩展的核心目录
├── hooks/          # React/Solid 钩子（默认自动导入）
├── modules/        # 本地 WXT 模块
├── public/         # 原样复制进产物的静态文件
├── utils/          # 通用工具函数（默认自动导入）
├── .env            # 环境变量
├── app.config.ts   # 运行时配置
├── wxt.config.ts   # WXT 主配置
├── web-ext.config.ts # 开发浏览器启动配置
└── tsconfig.json   # TypeScript 配置

生成目录：不要手改

.output/ 是构建产物，.wxt/ 是 WXT 生成的类型与配置（如 tsconfig、自动导入声明）。两者都是生成物：手改会在下次运行时被覆盖，也不应提交 git。你的代码只写在自己的源码目录里。

entrypoints/：唯一的入口约定

entrypoints/ 是 WXT 的约定目录，里面的文件会打包进扩展并登记到 manifest。一个入口点 = 一个文件，或一个带 index 文件的目录：

entrypoints/
├── background.ts        # 单文件入口：后台
├── content.ts           # 单文件入口：内容脚本
└── popup/               # 目录入口：弹窗
    ├── index.html       # 入口文件本身
    ├── main.ts          # 配套代码
    └── style.css

判断标准很简单：浏览器要单独打包或在 manifest 注册它，就放 entrypoints/；只是被页面 import 的组件，放别处。也别把配套文件直接丢在 entrypoints/ 根下——WXT 会把它们也当成入口尝试构建，通常会报错。入口类型与命名规则的完整讲解见 §07。

代码该放哪：一套判断规则

• 多个界面复用的 UI 组件 → components/；
• 不依赖具体界面的业务逻辑或浏览器封装 → utils/ 或自建 lib/；
• 需要打包和哈希处理的资源 → assets/；
• 必须保持原文件名、原样复制的资源（logo、字体）→ public/；
• 入口要薄，能力要共享：入口文件只做装配，可复用逻辑下沉到共享目录。

想要 src/ 目录？改一行配置

很多人习惯把源码和配置分开。在 wxt.config.ts 里加一行：

// wxt.config.ts
export default defineConfig({
  srcDir: 'src',
});

之后 entrypoints、assets、components 等目录全部移入 src/ 下，public/、modules/ 和配置文件仍留在根目录。这样配置文件和源码分层，团队规范里很常见。

其他目录也能自定义

// wxt.config.ts
export default defineConfig({
  srcDir: "src",             // 默认 "."
  modulesDir: "wxt-modules", // 默认 "modules"
  outDir: "dist",            // 默认 ".output"
  publicDir: "static",       // 默认 "public"
  entrypointsDir: "entries", // 默认 "entrypoints"（相对 srcDir）
});

路径支持相对路径或绝对路径。

两个真实项目的对照

官方 Vue starter（wxt-nuxt-ui-starter）用默认结构：入口在 entrypoints/popup/（index.html 配 App.vue、main.ts），图标放 public/icon/，组件在 components/。mkext 模板则自定义为 srcDir: "src" + entrypointsDir: "app" + outDir: "build"，入口全在 src/app/ 下，业务封装在 src/lib/，词典在 src/locales/。

这说明结构不是死的：默认约定开箱即用，团队规范需要时改配置。两种风格各有取舍——默认结构少配置、贴近官方示例；src 结构让根目录干净，适合源码与配置分离的团队。

读别人项目时，先看 wxt.config.ts 再找目录，避免找错地方。

.wxt/ 和 .output/ 都是生成目录，记得加进 .gitignore——它们的内容每次构建都可能变，不该进版本库。

小结

项目结构就是“约定 + 可配置”。入口放 entrypoints，共享代码分层放，生成目录别碰。下一节学天天要用的命令。