如何使用 Cursor 同时开发多项目？

如何使用 Cursor 配置 Multi-Root Workspace

在日常开发中，我们经常需要同时处理多个关联项目（如前端、后端、公共组件库），在不同窗口间切换不仅低效，上下文不完善，还容易出错。Cursor 作为基于 VS Code 内核的编辑器，支持 Multi-Root Workspace（多个工作区）功能，能让你在一个窗口中高效管理多个项目。本文将详细介绍如何配置和使用这一功能。
关于你不知道的Cursor是一个系列，更多Cursor实用技巧也可关注公众号 AI近距离

一、什么是 Multi-Root Workspace？

Multi-Root Workspace 是一种将多个独立项目文件夹整合到单一工作区的机制，它通过一个配置文件定义项目集合和工作区设置，实现：

在一个窗口中同时浏览、编辑多个项目代码

统一配置编辑器行为（如缩进、代码检查规则）

跨项目搜索、跳转和调试

对于前后端分离、微服务架构等场景，这一功能能显著提升开发效率。

二、配置 Multi-Root Workspace 的步骤

1. 理解配置文件格式

多个工作区通过 .code-workspace 后缀的 JSON 文件配置，核心结构包含：

folders：需要包含的项目文件夹列表

settings：工作区级别的编辑器配置（可选）

基础示例：

 {
    "folders": [
        {
            "name": "前端项目",  // 显示名称（可选）
            "path": "./frontend"// 项目路径（必填）
        },
        {
            "name": "后端项目",
            "path": "../backend"
        }
    ],
    "settings": {
        "editor.tabSize": 2,  // 工作区全局设置
        "files.exclude": { "**/node_modules": true }
    }
}

2. 创建工作区配置文件

方法一：手动创建（推荐）

新建文本文件，命名为[工作区名称].code-workspace（如fullstack.code-workspace）

{
  "folders": [
    {
      "name": "前端项目",  // 文件夹在工作区中的显示名称（可选）
      "path": "./frontend"// 项目文件夹路径（相对路径或绝对路径,推荐使用相对路径）
    },
    {
      "name": "后端项目",
      "path": "../backend"// 可以是不同位置的文件夹
    },
    {
      "name": "共用组件库",
      "path": "/Users/username/shared-components"// 绝对路径示例
    }
  ],
"settings": {
    // 工作区级别的设置（会覆盖单个项目的设置）
    "editor.tabSize": 2,
    "files.exclude": {
      "**/node_modules": true
    }
  }
}

2.按上述格式填写项目路径和设置

3.保存文件到任意位置（建议放在项目集群的根目录）

团队约定结构： my-team-workspace/ 
├─ fullstack.code-workspace ← 提交到共享仓库 
├─ frontend/ ← 独立仓库，成员各自克隆 
├─ backend/ ← 独立仓库，成员各自克隆 
└─ common/ ← 独立仓库，成员各自克隆

方法二：通过 Cursor 界面创建

打开 Cursor，点击菜单栏File → Add Folder to Workspace...


2.  依次选择需要添加的项目文件夹

点击File → Save Workspace As...，生成.code-workspace文件

3. 打开和管理工作区

打开方式：双击 .code-workspace 文件，或通过File → Open Workspace from File...选择文件

添加项目：在资源管理器顶部点击 Add Folder to Workspace

移除项目：右键点击项目文件夹，选择 Remove Folder from Workspace

修改配置：点击 File → Edit Workspace 直接编辑 .code-workspace 文件

4. 开始使用cursor agent 开发多工作区内容

四、高级配置技巧

1. 排查并过滤不需要的文件 / 目录

多项目共存时，大量冗余文件（如依赖目录、日志文件）会干扰浏览和搜索，可通过工作区设置精准过滤：

（1）隐藏指定文件 / 目录（不显示在资源管理器中）

在 settings 中配置 files.exclude，支持通配符匹配：

{
    "settings": {
        "files.exclude": {
            // 排除所有项目中的node_modules
            "**/node_modules": true,
            // 排除前端项目的dist目录
            "frontend/**/dist": true,
            // 排除所有.git目录
            "**/.git": true,
            // 排除特定类型文件（如.log、.tmp）
            "**/*.log": true,
            "**/*.tmp": true
        }
    }

（2）排除搜索范围（不参与全局搜索）

若某些目录无需搜索（如编译产物），可配置search.exclude：

{
    "settings": {
        "search.exclude": {
            // 搜索时忽略backend项目的vendor目录
            "backend/vendor/**": true,
            // 忽略所有项目的测试报告目录
            "**/coverage": true
        }
    }
}

（3）快速排查冗余文件

通过 Ctrl+Shift+F（全局搜索）输入**，查看搜索结果中是否包含无需显示的文件，再针对性添加排除规则。

2. 为项目添加别名（提升辨识度）

当项目文件夹名称不直观（如repo1、proj2），或存在同名项目时，可通过name字段设置别名，资源管理器中会显示别名而非原始文件夹名：

"folders": [
  {
    "name": "用户中心-前端",  // 显示别名
    "path": "./user-frontend"  // 实际路径
  },
  {
    "name": "用户中心-后端",
    "path": "../user-service"
  },
  {
    "name": "公共组件库（v2.0）",  // 可标注版本等信息
    "path": "/projects/common-lib"
  }
]

优势：在资源管理器中快速区分项目功能、版本或环境，尤其适合微服务架构中包含多个相似名称项目的场景。

五、版本控制与团队共享

1. 提交什么到代码仓库？

必须提交：.code-workspace 文件（它仅记录项目组织关系，不包含代码）

无需提交：各项目文件夹（它们通常已有独立的 Git 仓库管理自身代码）

2. 共享工作区的正确方式

将 .code-workspace 文件提交到团队共享仓库（可单独创建一个配置仓库，或放在主项目仓库中）

团队成员拉取该文件后，按约定的相对结构组织本地项目

双击 .code-workspace 文件即可加载完整工作区

3. 示例协作流程

团队约定结构：
my-team-workspace/
├─ fullstack.code-workspace  ← 提交到共享仓库
├─ frontend/  ← 独立仓库，成员各自克隆
├─ backend/   ← 独立仓库，成员各自克隆
└─ common/    ← 独立仓库，成员各自克隆

六、常见问题与解决方案

1. 团队成员的项目路径不一致？

无需统一绝对路径，只需确保每个人的本地目录符合约定的相对结构（如 workspace文件与frontend 同级）。

2. 工作区设置不生效？

工作区设置（settings字段）优先级高于项目本地设置和全局设置，若不生效可检查是否存在配置冲突。

3. 双击.code-workspace 文件打开工作区后，如何查看该文件内容？

当双击 .code-workspace 文件打开工作区后，该文件不会自动显示在工作区的资源管理器中，可通过以下方式查看其内容：

方法一：通过 Cursor 菜单操作

在打开工作区的状态下，点击顶部菜单栏的 File → Edit Workspace，Cursor 会直接打开当前工作区对应的 .code-workspace 文件，可查看和编辑其 JSON 配置内容。

方法二：通过文件系统手动打开

找到.code-workspace文件在本地的实际存储路径（如/Users/username/project/fullstack.code-workspace），右键点击文件，选择 Open with → Cursor，该文件会在当前工作区中以标签页形式打开，此时即可查看内容。

方法三：通过资源管理器添加到工作区

在工作区的资源管理器中，点击 Add Folder to Workspace，选择 .code-workspace 文件所在的文件夹并添加。添加后，在资源管理器中找到该文件夹，即可看到 .code-workspace 文件，双击即可打开查看。

总结

Multi-Root Workspace 是 Cursor 中管理多项目的高效工具，通过合理配置 .code-workspace文件和使用相对路径，能显著提升团队协作效率。核心要点是：

用 .code-workspace 文件定义项目集合

利用高级配置过滤冗余文件、设置项目别名

优先使用相对路径确保跨环境兼容性

仅提交配置文件，与项目代码仓库分工协作

掌握这一技能，让多项目开发从此告别窗口切换的繁琐！高效组织复杂项目，并且可以使用完整的上下文去开发全栈项目，大大提升跨项目开发效率

转自：https://mp.weixin.qq.com/s/Cfa6Gd8NIjhzaexJ5MjpZg