AI时代前端工程师实战指南：Cursor实战

发表于 分类于 阅读次数：

AI时代前端工程师实战指南：Cursor实战

学会 Cursor 的正确打开方式，从”只会 Tab 补全”到”熟练使用 Agent 模式”。在开始之前，先了解 Cursor 的两个重要配置文件：.cursorrules（项目根目录）和 .cursor/rules/*.mdc（.cursor/rules/ 目录），它们决定了 AI 的行为规范。

3.1 三种模式与使用场景

Cursor 有三种交互模式，分别对应不同场景：

模式 触发方式 最佳场景 不要用它做
Tab 补全 自动触发（灰色提示文字按 Tab） 写已知模式的代码、重复性编码 复杂逻辑、跨文件操作
Ctrl+K (Inline Edit) 选中代码后按 Ctrl+K 修改单段代码、解释代码、重构函数 创建新文件、多文件修改
Ctrl+I (Composer) Ctrl+I 这是 Cursor 的核心能力 简单改一行变量名（Tab 更快）

Composer 有两种子模式：Normal（对话式，你一步步引导）和 Agent（自主式，AI 自己规划执行）。

选型决策树

1
2
3
4
5
6
7
8
我想让 Cursor 做什么？
│
├─ 写一行已知模式的代码 → Tab 补全
├─ 修改当前函数/组件 → Ctrl+K
├─ 写一个新函数/组件（有清晰的需求）→ Ctrl+I Normal
├─ 写一个涉及多文件的新功能 → Ctrl+I Agent
├─ Debug 一段报错 → Ctrl+K 选中报错区域
└─ 理解一个文件或文件夹 → Ctrl+K "解释这个文件"

3.2 Agent 模式完全指南

Agent 模式是 Cursor 和 VS Code + Copilot 的本质区别。

Agent 能做什么

  • 自动读取多个文件来理解上下文
  • 创建、修改、删除文件
  • 在终端运行命令（npm install、git commit 等）
  • 自主规划步骤并执行

Agent 不能做什么

  • 不能记住上次会话的内容（每次启动都是新会话）
  • 不能保证生成的代码 100% 正确（需要你验证）
  • 不能用自然语言理解复杂的业务逻辑（它不理解你的业务，只理解代码）

Agent 模式的最佳实践

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
✅ 好的 Agent Prompt 结构：

【目标】实现一个防抖搜索组件
【约束】
- 使用 Vue 3 Composition API
- 输入框 300ms 防抖后调用 API
- API 路径：/api/search?q={keyword}
- 显示加载状态和空状态
【参考文件】
- @src/components/Input.vue（参考现有的输入组件风格）
- @src/api/search.ts（参考现有的 API 调用方式）

❌ 差的 Agent Prompt：
实现一个搜索组件
（太模糊，AI 会按自己的假设做，结果大概率不符合预期）

关键技巧：用 @ 精准控制上下文

指令 用法 作用
@File @src/components/Button.tsx 引用特定文件
@Folder @src/components/ 引用整个文件夹
@Code @Code(变量名或类型) 引用代码中的特定符号
@Docs @Docs Vue 引用官方文档（需要先添加文档源）
@Web @Web React 19 新特性 联网搜索（Composer + Agent 模式可用）
@Terminal 在 Composer 中 引用终端输出来辅助 Debug
@Problems 在 Composer 中 引用 LSP 错误列表

配置 @Docs：Settings → Features → Docs → Add Doc，可以添加 Vue、React、Tailwind 等官方文档源。之后在对话中 @Docs Vue 就能引用最新的官方文档。

3.3 Debug 最佳实践

直接把报错信息贴给 AI 是最差的 Debug 方式。

Debug 的正确姿势

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
❌ 错误方式：
"这个报错怎么解决？"
（贴了一行错误信息，没有任何上下文）

✅ 正确方式：

【错误现象】
@Terminal（最后一次终端输出）
或 @Problems（LSP 错误列表）
或 选中报错代码区域按 Ctrl+K

【代码上下文】
@相关的文件引用

【我尝试过的】
- 已经检查了 API 返回的数据格式
- 确认了参数类型匹配

【期望行为】
点击提交按钮后应该调 API 发送数据，但现在点了没反应

Debug 的四个层次

层次 做法 效果
L1 贴报错信息 20% 能解决，通常是因为缺少上下文
L2 贴报错 + 相关代码 60% 能解决，AI 能看到上下文
L3 贴报错 + 代码 + 你怀疑的原因 80% 能解决，AI 可以验证你的假设
L4 让 Cursor Agent 自己复现问题 90% 能解决，Agent 可以运行代码、加日志、定位根因

L4 示例：

1
2
3
4
5
6
这个组件有个 bug：在筛选条件变化后，列表数据没有刷新。
请帮我：
1. 先理解当前的数据流（读取 @src/stores/productStore.ts 和相关文件）
2. 在关键路径上加 console.log
3. 告诉我问题出在哪里
4. 给出修复方案

3.4 用 Cursor 理解遗留代码

面对一个陌生的大型代码库，不用从头读到尾。

1
2
3
4
5
6
7
8
9
10
请帮我理解这个文件夹的结构和功能：

@src/modules/report/

请输出：
1. 这个模块的核心职责
2. 文件结构和每个文件的作用
3. 数据流向（数据从哪里来，到哪里去）
4. 关键函数和组件的调用链
5. 如果我要加一个"导出 PDF"功能，应该改哪些文件

理解代码的三个层次

层次 做法 能做什么
宏观 @Folder + 问”这个模块是做什么的” 理解模块职责和文件结构
中观 @File + “解释这个组件的逻辑” 理解单个文件的职责
微观 选中代码 + Ctrl+K “解释这段逻辑” 理解具体实现细节

3.5 Cursor 配置

.cursorrules 文件（项目根目录）

.cursorrules 是 Cursor AI 的行为配置文件。放在项目根目录，Cursor 会自动读取。

必配内容：

  • 项目的技术栈（框架、语言、构建工具）
  • 代码风格偏好
  • 项目结构约定
  • 命名规范

以下是一个完整的 .cursorrules 配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
# .cursorrules — Cursor 项目规则文件
# 位置：项目根目录
# 作用：定义 Cursor AI（Tab 补全 / Ctrl+K / Agent）的行为规范
# 文档：https://docs.cursor.com/context/rules-for-ai

你是一个资深前端工程师，精通 Vue 3、React、TypeScript。

## 技术栈
- 框架：Vue 3 (Composition API) / React 18+
- 构建：Vite
- 样式：Tailwind CSS
- 语言：TypeScript (strict mode)
- 状态管理：Pinia / Zustand
- 测试：Vitest + Testing Library

## 代码风格
- 使用 Composition API 的 `<script setup>` 语法（Vue 项目）
- 使用 React Hooks 和函数组件（React 项目）
- 优先使用 `const` 而非 `let`
- 避免 `any` 类型，使用 `unknown` 代替
- 组件名使用 PascalCase，文件使用 kebab-case
- 使用 named export 而非 default export

## 核心原则
1. 生成的代码要有完整的 TypeScript 类型定义
2. 每个组件职责单一，不超 300 行
3. 逻辑复用优先使用 composable / custom hooks
4. 性能敏感场景主动考虑 memo / virtual scroll / lazy load
5. 错误处理全覆盖：try-catch + 用户友好的错误提示

## 项目结构
src/
├── components/     # 通用组件
├── composables/    # 逻辑复用（Vue）
├── hooks/          # 逻辑复用（React）
├── views/          # 页面级组件
├── api/            # API 调用
├── stores/         # 状态管理
├── types/          # 类型定义
└── utils/          # 工具函数

## 测试要求
- 工具函数和 composable 必须有单元测试
- 测试文件与源文件同目录，命名为 `*.test.ts`

.cursor/rules/*.mdc（新版规则系统）

Cursor 新版支持按文件路径匹配的规则。

1
2
3
4
.cursor/rules/
├── frontend-standards.mdc     # 全局前端规范
├── vue-components.mdc         # Vue 组件相关规则
└── api-layer.mdc             # API 层相关规则

每个 .mdc 文件头部可以定义匹配规则：

1
2
3
4
---
description: Vue 组件规范
globs: src/**/*.vue
---

以下是一个完整的 .mdc 规则文件示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# 新版 Cursor 规则文件 (.mdc 格式)
# 位置：.cursor/rules/（需要手动创建 .cursor/rules/ 目录）
# 说明：Cursor 新版规则系统支持按文件路径匹配自动激活
# 文件名建议：frontend-standards.mdc
# 参考：https://docs.cursor.com/context/rules-for-ai

---
description: 前端代码规范和项目约定
globs: src/**/*.{ts,tsx,vue}
---

## 技术栈规则
- 使用 TypeScript strict 模式
- 框架：Vue 3 Composition API + `<script setup>`
- 样式：Tailwind CSS 优先
- 状态管理：Pinia

## 组件设计规范
- 每个组件职责单一，不超过 300 行
- Props 定义使用 `withDefaults` + 类型声明
- 事件使用 `defineEmits` 声明
- 复杂组件抽取 composable 分离逻辑

## 命名规范
- 组件文件：PascalCase（`UserProfile.vue`）
- Composables：`use` 前缀 + camelCase（`useUserAuth.ts`）
- 类型定义：`interface` 前缀 `I`（`IUser`）或 PascalCase（推荐 `User`）
- 枚举：PascalCase（`UserRole.Admin`）

## 代码质量
- 禁止 `any`，使用 `unknown` 替代
- 禁止 `@ts-ignore` / `@ts-expect-error`
- 禁止空的 catch 块
- 异步函数必须有错误处理

3.6 常见陷阱

陷阱 表现 原因 解决
Context 溢出 AI 开始胡言乱语 对话太长，超出上下文窗口 开新会话，上下文精简
Agent 循环 Agent 陷入死循环改同一个文件 目标不明确或约束不足 终止后重新明确限制条件
幻觉 API AI 用了不存在的 API/配置 知识截止日期前的 API 变化 开启 @Docs 或 @Web 模式
过度修改 Agent 改了你不希望改的文件 没有在 Prompt 中指定范围 明确 “请不要修改 xxx 文件”
代码不一致 新代码风格和项目不一致 没有配置 .cursorrules 配置 .cursorrules 文件