AI 编程提效实战：Cursor 从安装到写完一个项目（2026 超详细图文）

读完这篇你能得到：一个装好、配好、能用国产大模型驱动的 Cursor，外加亲手用它从零写完的一个可运行的「待办清单 API」小项目（含完整代码）。全程基于 2026 年最新版实测，每一步配命令，踩过的坑都标了出来。

网上的 Cursor 教程要么停在「点这里安装」就没了，要么版本一变全是过时截图，跟着做总在「配置模型」「项目里到底怎么让它帮我写」这两步卡住。这篇不一样：我把「装 → 配 → 真写一个项目 → 排错」整条链路走了一遍，你照着做一遍就能上手。

一、Cursor 是什么，为什么值得花这半小时

一句话：Cursor 是一个内置了 AI 的代码编辑器（基于 VS Code 魔改），核心能力有三个——

• Tab 自动补全：写一半，它补下一段，按 Tab 接受。
• Cmd/Ctrl+K 行内改写：选中代码，告诉它「把这段改成异步」，它当场改。
• Cmd/Ctrl+L 对话 + Composer：让它读你的整个项目、跨多个文件改代码。

真正拉开效率差距的不是补全，而是 Composer 多文件编辑：你描述需求，它直接在多个文件里落代码。下面的项目实战就用它。

二、前置环境（先对齐，避免「我这儿不一样」）

本文以 Windows 11 为例，macOS/Linux 步骤一致，只是安装包不同。

三、最短可跑通路径（5 步先跑起来）

能走到第 5 步看到它生成代码，说明环境就绪。下面进入正式配置和项目实战。

四、分步详解

4.1 安装与首次登录

下载后安装包约 100–200MB。安装完成首次启动会让你选择：是否从 VS Code 导入配置（扩展、快捷键、主题）。如果你本来用 VS Code，选「导入」能无缝迁移。

登录这一步是新手第一个坎：注册后默认有官方提供的免费额度（Free 计划），足够你跑通本文全部内容。额度用量可在 Settings → 账户里查看。

4.2 配置模型：用国产大模型 API 驱动 Cursor（关键省钱点）

Cursor 默认用内置模型，免费额度有限。一个完全合规、可长期低成本使用的做法是：填入你自己申请的国产大模型 API Key（如 DeepSeek 官方 API），用它来驱动对话与补全。

步骤：

Settings → Models → OpenAI API Key
├─ Override Base URL: https://api.deepseek.com
├─ API Key: sk-xxxxxxxxxxxxxxxx
└─ Model: deepseek-chat

为什么走官方 API：合规、稳定、按量计费可控，比依赖有限免费额度更适合长期高频使用。

4.3 项目实战：用 Composer 写一个「待办清单 API」

现在动真格。目标：用 FastAPI 写一个增删查待办事项的 HTTP 接口。

第一步，建项目骨架。在 Cursor 打开的空文件夹里，按 Ctrl+I 打开 Composer，输入：

用 FastAPI 写一个待办清单 API，要求：
1. 内存里用一个 list 存待办，每条有 id、title、done 三个字段
2. 提供 4 个接口：GET /todos 列出全部、POST /todos 新增、
PUT /todos/{id} 标记完成、DELETE /todos/{id} 删除
3. 生成 requirements.txt
4. 代码放在 main.py

Composer 会生成 main.py 和 requirements.txt 两个文件，并在界面上显示 diff。检查无误后点 Accept All 接受。

生成的 main.py 大致是这样（实测可跑）：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI(title="Todo API")

class Todo(BaseModel):
title: str
done: bool = False

_todos: list[dict] = []
_next_id = 1

@app.get("/todos")
def list_todos():
return _todos

@app.post("/todos")
def add_todo(todo: Todo):
global _next_id
item = {"id": _next_id, "title": todo.title, "done": todo.done}
_todos.append(item)
_next_id += 1
return item

@app.put("/todos/{todo_id}")
def complete_todo(todo_id: int):
for t in _todos:
if t["id"] == todo_id:
t["done"] = True
return t
raise HTTPException(status_code=404, detail="todo not found")

@app.delete("/todos/{todo_id}")
def delete_todo(todo_id: int):
global _todos
before = len(_todos)
_todos = [t for t in _todos if t["id"] != todo_id]
if len(_todos) == before:
raise HTTPException(status_code=404, detail="todo not found")
return {"deleted": todo_id}

第二步，跑起来。打开 Cursor 内置终端（Ctrl+反引号）：

python -m venv .venv
.venv\\Scripts\\activate # Windows；macOS/Linux 用 source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app –reload

浏览器打开 http://127.0.0.1:8000/docs，FastAPI 自动生成的交互式文档就出来了，可以直接点按钮调每个接口。

第三步，让 AI 帮你加功能。选中 add_todo 函数，按 Ctrl+K，输入「加一个 title 不能为空的校验，空标题返回 400」。它会当场改好这一段。

这就是 Cursor 的核心工作流：Composer 起骨架 → 终端验证 → Ctrl+K 局部迭代。

五、常见报错与解决（收藏级）

报错 1：Verify 模型时报 401 / Incorrect API key

• 根因：Base URL 没改，或 Key 复制时带了空格。
• 解法：确认 Base URL 是 https://api.deepseek.com，Key 前后无空格，模型名为 deepseek-chat。

报错 2：uvicorn: command not found / 不是内部命令

• 根因：虚拟环境没激活，或依赖没装进当前环境。
• 解法：先确认终端行首有 (.venv)，再 pip install -r requirements.txt。

报错 3：Address already in use 端口被占

• 根因：上一次的 uvicorn 没关。
• 解法：换端口 uvicorn main:app –reload –port 8001，或结束占用 8000 的进程。

报错 4：Composer 生成的代码引用了未安装的库

• 根因：它生成了 requirements 但你没装，或装漏了。
• 解法：把报错信息整段粘进 Ctrl+L 对话框，让它告诉你缺哪个包、怎么装。

报错 5：中文注释/字符串变成乱码

• 根因：文件编码不是 UTF-8。
• 解法：右下角点编码 → Save with Encoding → UTF-8。

六、验证成功的标志

• 能打开 http://127.0.0.1:8000/docs；
• 在文档页 POST 一条待办、再 GET 能看到它；
• 用 Ctrl+K 改一段代码，保存后 –reload 自动重载、接口行为随之变化。

三条都满足，你已经完整跑通了「用 Cursor 写一个项目」。

七、下一步

把这套流程用到你自己的真实需求上：先用 Composer 起骨架，再用终端验证，最后用 Ctrl+K 迭代。下一篇我会讲「用 Cursor 接管一个已有项目的重构」，关注大鹏AI教育，持续更新 AI 实战。

完整代码：本文的 main.py 与 requirements.txt 已在上文完整给出，直接复制到 Cursor 打开的文件夹即可跑通，无需额外下载。

建议收藏：下次配 Cursor 或排查模型接入问题，直接翻这篇照抄。卡在哪一步，把报错原文贴评论区，我帮你看。