使用 src 目录组织源代码

您可以将项目的源代码文件统一放置在 src 子目录中，而不是分散在项目根目录下。这种组织结构有助于保持项目的整洁性和可维护性。

快速创建带 src 目录的项目

创建一个包含 src 目录结构的 Plasmo 项目非常简单：


pnpm create plasmo --with-src

上述命令利用了 Plasmo 的示例模板功能，会自动为您设置好完整的目录结构。

重要注意事项：

请确保 assets 目录位于项目根目录中，而不是 src 目录内
所有源代码文件，包括 Plasmo 的入口文件（如 popup.tsx、options.tsx、background.ts、contents/* 等），都必须放在 src 目录中
如果入口文件没有正确放置在 src 目录中，Plasmo 将无法找到这些文件，导致构建出的扩展程序为空

此配置仅将 ~ 别名解析为 /src 用于源代码模块导入。详细说明请参考波浪号导入解析文档。

手动配置 src 目录

如果您需要为现有项目添加 src 目录支持，可以按照以下步骤操作：

第一步：移动源代码文件

首先，将所有源代码文件移动到新创建的 src 目录中：


# 创建 src 目录
mkdir src
 
# 移动源代码文件（根据实际情况调整）
mv popup.tsx options.tsx background.ts contents/ src/

第二步：配置 TypeScript 路径映射

为了使 TypeScript 能够正确解析 src 目录中的模块，需要在 tsconfig.json 文件中配置路径映射：


{
  "extends": "plasmo/templates/tsconfig.base",
  "exclude": ["node_modules"],
  "include": [".plasmo/index.d.ts", "./**/*.ts", "./**/*.tsx"],
  "compilerOptions": {
    "paths": {
      "~*": ["./src/*"]
    },
    "baseUrl": "."
  }
}

第三步：更新导入语句

确保所有导入语句都使用正确的路径。原来直接导入的文件现在需要加上 ~/ 前缀或使用相对路径：


// 原来的导入方式
import { utils } from "./utils"
 
// 新的导入方式（使用别名）
import { utils } from "~/utils"
 
// 或者使用相对路径
import { utils } from "../utils"

项目结构对比

默认结构


project/
├── popup.tsx
├── options.tsx
├── background.ts
├── contents/
│   └── content.ts
└── assets/
    └── icon.png

使用 src 目录的结构


project/
├── src/
│   ├── popup.tsx
│   ├── options.tsx
│   ├── background.ts
│   └── contents/
│       └── content.ts
└── assets/
    └── icon.png

优势与最佳实践

使用 src 目录结构具有以下优势：

代码组织更清晰：源代码与配置文件、构建产物分离
更好的可维护性：便于团队协作和代码审查
减少根目录混乱：保持项目根目录的整洁
标准化结构：符合大多数前端项目的目录规范

最佳实践建议：

在项目开始时就决定是否使用 src 目录结构
如果团队已有其他项目使用类似结构，建议保持一致
对于小型项目或简单示例，使用默认结构可能更简洁

有关完整示例，请参考 with-src 示例项目。