跳到主要内容

使用 Cursor Canvas 进行可视化项目规划

Canvas

Cursor Canvas 是一个位于 IDE 内部的可视化规划界面。它让您可以绘制架构图、映射功能流程、规划冲刺任务，并与团队共享可视化上下文，所有这些都不需要离开 Cursor。与静态白板不同，Canvas 与您的代码库集成，允许您将图表链接到实际的文件、函数和数据模型。本指南涵盖从创建第一个画布到发布它以及故障排除臭名昭著的"Canvas file not found"错误的所有内容。

什么是 Cursor Canvas？​

Canvas 是一个可视化工作区，您可以：

  • 绘制架构图，使用方框、箭头和注释
  • 链接代码工件，通过将文件、函数或类拖放到画布上
  • 可视化规划功能，在编写任何代码之前
  • 与团队共享，通过将画布发布为独立链接
  • 注释决策，使用笔记、TODO 和设计理由

与 Miro 或 Figma 等外部工具的关键区别在于 Canvas 具有上下文感知能力。当您在画布上放置一个组件时，它知道该组件的实际文件路径、导出和依赖项。

前置条件​

  • Cursor 版本 0.42 或更高（Canvas 于 2024 年底引入）
  • 在 Cursor 中打开的项目文件夹（Canvas 在项目上下文中工作）
  • 用于发布功能的 Cursor 账户（免费层即可）

创建您的第一个画布​

步骤一：打开画布编辑器​

有三种方式打开新画布：

  1. 命令面板： Cmd/Ctrl + Shift + P 并输入 Canvas: New Canvas
  2. 侧边栏： 点击活动栏（左侧边栏）中的 Canvas 图标
  3. 键盘快捷键： Cmd/Ctrl + Shift + C（可在设置中配置）

步骤二：向画布添加元素​

从空白画布开始。您可以添加以下元素类型：

元素添加方式用途
文件节点从资源管理器拖拽文件显示文件及其关系
函数节点右键点击函数 > "Add to Canvas"可视化函数调用图
文本框双击空白画布区域添加笔记、标签或决策
形状点击工具栏中的形状工具绘制方框、圆形、箭头
图片拖拽图片文件或从剪贴板粘贴包含截图或模型图

步骤三：连接元素​

在元素之间绘制箭头以显示关系：

  1. 将鼠标悬停在元素上直到出现连接点
  2. 从连接点点击并拖动到另一个元素
  3. 释放以创建连接
  4. 可选择为连接添加标签（例如"imports"、"calls"、"extends"）

步骤四：保存画布​

画布保存为项目中的 .canvas 文件：

my-project/
  .cursor/
    canvases/
      architecture-overview.canvas
      feature-auth-flow.canvas
      sprint-planning.canvas
提示

为画布使用描述性名称。Canvas 文件可以版本控制，因此您的团队可以跟踪图表随时间的演变。将 canvases/ 文件夹添加到您的仓库并随代码一起提交。

画布发布​

发布画布会生成一个可共享的链接，任何人都可以在浏览器中查看，即使没有安装 Cursor。这对于与利益相关者共享架构决策或为新团队成员进行入职培训非常有用。

如何发布​

  1. 打开要发布的画布
  2. 点击右上角工具栏中的 Publish 按钮
  3. 选择可见性：
    • Private - 只有拥有链接和 Cursor 账户的人可以查看
    • Unlisted - 任何拥有链接的人都可以查看（无需账户）
    • Public - 任何人都可以发现和查看
  4. 点击 Publish
  5. 复制生成的 URL 并共享

发布的内部工作原理​

当您发布画布时，Cursor 会：

  1. 将画布序列化为可移植格式
  2. 上传到 Cursor 的云存储
  3. 为发布的版本生成唯一的项目密钥
  4. 返回包含该密钥的 URL
注意

已发布的画布是时间点快照。如果您在发布后更新画布，已发布版本不会自动更新。您必须重新发布以共享最新版本。这是设计如此，以防止利益相关者看到半成品的编辑。

项目密钥管理​

每个画布，无论是本地的还是已发布的，都与一个项目密钥关联。了解项目密钥的工作方式对于故障排除发布问题至关重要。

什么是项目密钥？​

项目密钥是一个唯一标识符，它将画布与其项目上下文链接。它允许已发布的画布引用正确的代码结构、文件路径和元数据。

每次启动的临时项目密钥问题​

论坛用户经常报告画布发布失败并出现"Canvas file not found"。根本原因是当 Cursor 找不到持久项目密钥时，会在每次启动时生成一个临时项目密钥。

以下发生的情况：

  1. 您打开 Cursor，它分配了一个临时项目密钥，如 tmp_abc123
  2. 您创建并编辑一个画布，该画布与 tmp_abc123 关联
  3. 您点击发布
  4. 发布端点按当前项目密钥查找画布
  5. 如果密钥已更改（因为 Cursor 被重启），查找失败
  6. 您看到"Canvas file not found"

修复项目密钥问题​

方案一：创建持久项目密钥​

在项目根目录添加一个 .cursor/project.json 文件：

{
  "projectKey": "persistent-key-my-project-2024",
  "projectName": "My Project",
  "createdAt": "2024-01-15T10:00:00Z"
}

这确保项目密钥在 Cursor 重启后保持稳定。

提示

使用描述性的、唯一的项目密钥。不要使用 project1 或 test 等通用值。如果您的机器上的两个项目具有相同的密钥，画布查找可能会冲突，发布将间歇性失败。

方案二：重新关联画布​

如果您已经有一个带有过期临时密钥的画布：

  1. 在 Cursor 中关闭画布
  2. 在文本编辑器中打开 .canvas 文件
  3. 找到 projectKey 字段
  4. 将其更新为与您的持久密钥匹配
  5. 保存并在 Cursor 中重新打开
  6. 尝试再次发布

.canvas 文件基于 JSON，相关部分如下所示：

{
  "version": "1.0",
  "projectKey": "tmp_abc123",
  "elements": [...],
  "connections": [...]
}

将 tmp_abc123 更改为您的持久密钥。

方案三：清除画布缓存​

如果以上方案都不起作用，本地画布缓存可能已损坏：

  1. 关闭 Cursor
  2. 导航到 Cursor 缓存目录：
    • macOS： ~/Library/Application Support/Cursor/canvas-cache/
    • Windows： %APPDATA%/Cursor/canvas-cache/
    • Linux： ~/.config/Cursor/canvas-cache/
  3. 删除 canvas-cache 文件夹的内容
  4. 重新打开 Cursor
  5. 重新打开您的画布文件
  6. 尝试再次发布
注意

清除画布缓存不会删除您的 .canvas 文件（那些位于您的项目中）。它只删除将项目密钥映射到画布元数据的临时查找表。您的实际画布内容会被保留。

独立版与 Glass App 画布​

Canvas 在 Cursor 生态系统中有两种可用上下文，它们之间存在重要差异。

独立画布（Cursor IDE）​

这是您从 Cursor 编辑器中访问的画布：

  • 位于您的 .cursor/canvases/ 目录中
  • 直接链接到您打开的项目
  • 可以从资源管理器拖拽文件到画布上
  • 使用 .cursor/project.json 中的项目密钥
  • 最适合：面向开发者的图表、架构规划、代码映射

Glass App 画布​

Glass 是 Cursor 的独立可视化应用（与 IDE 分离）。Glass 中的 Canvas：

  • 位于 Glass 自己的存储中，而不是您的项目目录
  • 可以链接到项目但独立运行
  • 具有不同的项目密钥命名空间
  • 支持更丰富的可视化元素（动画、交互组件）
  • 最适合：演示、利益相关者演示、跨团队共享

关键差异​

功能独立画布Glass App 画布
存储位置.cursor/canvases/Glass 云存储
项目密钥来源.cursor/project.jsonGlass 项目设置
文件拖放是，从资源管理器否，必须导入
实时协作否是
发布范围Cursor 账户Glass 工作空间
离线编辑是否（需要连接）
提示

如果您主要在 Cursor IDE 中工作，请使用独立 Canvas 进行开发规划。当您需要向非技术利益相关者展示或实时协作时，使用 Glass App Canvas。两者不可互换，尝试使用 Glass Canvas 进行代码映射任务会令人沮丧，因为它无法引用实时文件。

在独立版和 Glass 之间迁移​

您可以导出独立画布并将其导入 Glass：

  1. 在 Cursor 中打开画布
  2. 点击 Export > Export as Glass-compatible
  3. 保存 .glass-canvas 文件
  4. 打开 Glass
  5. 点击 Import 并选择该文件

请注意，导出画布中的文件引用将转换为静态引用（如果底层代码更改，它们不会更新）。

可视化工作流设计​

Canvas 不仅用于架构图。它是一个通用的可视化工作区。以下是常见的工作流模式。

功能规划工作流​

  1. 创建一个名为 feature-[name]-plan.canvas 的画布
  2. 添加功能需求的文本框
  3. 为将要修改的文件添加文件节点
  4. 绘制箭头显示数据流
  5. 为未决问题添加 TODO 文本框
  6. 在实现之前与团队共享画布
  7. 在实现过程中将画布作为参考

代码审查工作流​

  1. 为正在审查的 PR 创建一个画布
  2. 将变更的文件拖到画布上
  3. 绘制变更函数的调用图
  4. 用红色文本框注释潜在问题
  5. 发布画布并在 PR 描述中链接

入职工作流​

  1. 创建一个 project-architecture.canvas 文件
  2. 添加主要入口点（例如 index.ts、app.tsx）
  3. 添加核心模块和服务
  4. 绘制依赖图
  5. 添加注释解释每个模块的职责
  6. 发布为未列出链接
  7. 在新团队成员第一天与他们共享
提示

保持入职画布高层次。一个有 200 个节点的画布比直接阅读代码更难理解。目标是 10-20 个展示大局的元素，让新员工深入了解代码以获取细节。

高级画布功能​

代码感知连接​

当您向画布添加函数或类时，Canvas 可以自动检测其依赖项并提供添加它们：

  1. 右键点击函数节点
  2. 选择 Show Dependencies
  3. Canvas 列出该函数使用的所有函数、模块和类型
  4. 点击任何依赖项将其添加到画布并自动绘制连接

画布模板​

为常见图表类型创建可重用的画布模板：

{
  "version": "1.0",
  "template": "microservice-architecture",
  "elements": [
    {"type": "text", "label": "API Gateway", "x": 400, "y": 50},
    {"type": "text", "label": "Auth Service", "x": 200, "y": 200},
    {"type": "text", "label": "User Service", "x": 600, "y": 200},
    {"type": "text", "label": "Database", "x": 400, "y": 350}
  ],
  "connections": [
    {"from": 0, "to": 1, "label": "routes to"},
    {"from": 0, "to": 2, "label": "routes to"},
    {"from": 1, "to": 3, "label": "reads/writes"},
    {"from": 2, "to": 3, "label": "reads/writes"}
  ]
}

将此保存为 .cursor/canvases/templates/microservice.canvas 并使用 Canvas: New from Template 来实例化它。

在文档中嵌入画布​

您可以在项目文档中嵌入已发布的画布链接：

## Architecture Overview

See our [visual architecture diagram](https://canvas.cursor.sh/c/persistent-key-my-project-2024/architecture-overview) for the full system map.

Key components:
- API Gateway handles routing
- Auth Service manages JWT verification
- User Service handles profile CRUD

常见问题故障排除​

问题：发布时出现"Canvas file not found"​

这是最常见的错误。按照上面的项目密钥故障排除步骤操作。如果这些步骤无法解决：

  1. 检查 .canvas 文件是否存在于磁盘上
  2. 验证文件是否未在其他应用程序中打开（文件锁）
  3. 确保您对 .cursor/canvases/ 目录有写入权限
  4. 检查您的网络连接（发布需要上传到云端）

问题：画布元素在重启后消失​

原因： 画布文件通过内部 ID 引用元素，如果底层代码结构更改（例如文件被重命名或删除），这些 ID 可能会改变。

解决方案：

  1. 打开画布
  2. 点击任何剩余元素
  3. 使用 Reconnect to file 将其重新链接到当前文件路径
  4. 重新添加任何缺失的元素

问题：发布链接显示空白页​

原因： 已发布 URL 中的项目密钥不匹配任何已存储的画布。

解决方案： 确保设置了持久项目密钥后重新发布画布。来自临时密钥画布的旧链接不会解析。

问题：画布性能下降​

原因： 超过 100 个元素的大型画布可能会减慢渲染速度。

解决方案：

  1. 将大型画布拆分为多个较小的画布
  2. 对元素组使用 Collapse 功能
  3. 移除未使用的连接
  4. 避免将整个目录作为单个节点添加（使用单个文件代替）
注意

不要将 node_modules/ 或其他大型目录添加到画布。每个文件都成为一个单独的节点，一个有 10,000 个文件的目录会使 Cursor 无响应。始终添加特定文件或函数，而不是整个文件夹。

最佳实践​

保持画布聚焦​

一个画布应该回答一个问题。与其创建一个"包含一切"的画布，不如创建：

  • data-flow.canvas - 数据如何在系统中流动
  • auth-architecture.canvas - 认证和授权流程
  • deployment-topology.canvas - 基础设施和部署映射
  • sprint-3-plan.canvas - 当前冲刺的可视化计划

版本控制您的画布​

.canvas 文件是基于文本的 JSON。将它们提交到您的仓库：

git add .cursor/canvases/
git commit -m "docs: update architecture canvas for new auth flow"

这为您提供了架构如何演变的历史，并让团队成员通过 PR 审查图表变更。

定期画布维护​

每个冲刺，审查您的画布：

  • 删除过时的图表
  • 更改已变更的架构
  • 移除对已删除文件的引用
  • 重新发布任何外部共享的画布

总结​

Cursor Canvas 将项目规划从一项断开的活动转变为集成的可视化工作流。"Canvas file not found"错误是用户面临的最常见问题，其根源在于每次启动的临时项目密钥机制，通过在 .cursor/project.json 中创建持久项目密钥可以完全解决。了解独立画布和 Glass App 画布之间的差异确保您在每个上下文中使用正确的工具，同时遵循本指南中的可视化工作流模式将使您的规划更有效，架构更具可传达性。