企业官网建设流程全解析

1. 为什么你的 Cursor 总是“自作主张”：从一次真实翻车说起

你有没有遇到过这种情况：让 Cursor 帮你改一个后端接口的返回格式，结果它顺手把整个 Controller 层的命名风格全改了，还“贴心”地删掉了你写了半天的注释。更崩溃的是，它把error: 0改成了code: 200，前端同学当场在群里 @ 你。

这不是 Cursor 笨，而是你没给它立规矩。Cursor Rules 就是 AI 编码助手的“员工手册”——它规定了 AI 在你项目里能做什么、不能做什么、用什么技术栈、返回什么结构、注释怎么写。没有 Rules 的 Cursor，就像一个刚入职但没人带的新人，技术能力很强，但完全不懂你们团队的规矩。

这篇是 Cursor 教程的第二篇，聚焦 Rules 配置实战。我会带你从零写出一套可直接复制的.cursorrules和.cursor/rules/*.mdc配置，覆盖后端、前端、接口文档三个场景，并给出用 VS Code 对照验证 Rules 是否生效的检查步骤。适合正在用 Cursor 做真实项目、被 AI 乱改代码困扰、想把提示词变成团队工程资产的开发者。

核心检索词先明确：Cursor Rules 是什么？它是 Cursor 读取的规则文件，用来约束 AI 编码助手的行为。能做什么？统一代码风格、固定返回结构、强制中文回复、限制修改范围。适合谁？所有用 Cursor 写生产代码的人，尤其是团队协作场景。

我试过在一个 Spring Boot 项目里不加任何 Rules，让 Cursor 连续改了三个接口，结果它每次返回结构都不一样，前端联调时直接炸了。后来把 Rules 配好，同样三个接口，AI 生成的代码结构完全一致，连注释格式都统一了。这就是 Rules 的价值：把“每次都要重复说的话”变成“一次配置，永久生效”。

2. Cursor Rules 的两种形态与目录结构：.cursorrules和.cursor/rules到底怎么选

在动手写配置之前，先把 Rules 的存放位置和生效范围搞清楚。Cursor 目前支持两种规则文件形态，很多人混着用，结果规则冲突，AI 行为诡异。

第一种是项目根目录下的.cursorrules文件。这是一个纯文本文件，没有 frontmatter，没有触发条件，只要在项目根目录，Cursor 就会自动读取。它的优点是简单直接，适合放“全局通用规则”，比如“始终用中文回复”“所有方法必须写注释”。缺点是所有规则一股脑塞进去，项目大了之后文件会非常长，而且没法针对特定文件类型做差异化控制。

第二种是.cursor/rules/目录下的.mdc文件。这是 Cursor 推荐的现代做法，每个规则文件独立，支持 frontmatter 元数据，可以设置alwaysApply、globs、description等字段，实现“始终应用”“按文件后缀应用”“手动 @ 引用”四种触发模式。团队协作场景强烈建议用这种，因为每个规则文件可以单独 review、单独修改，不会互相污染。

目录结构建议这样组织：

your-project/ ├── .cursorrules # 全局兜底规则（可选） ├── .cursor/ │ └── rules/ │ ├── 00-global.mdc # 全局：中文回复、提交规范 │ ├── 10-backend.mdc # 后端：分层、命名、异常处理 │ ├── 11-api-doc.mdc # 接口文档：同步更新规范 │ ├── 20-frontend.mdc # 前端：Vue3 + Vant 技术栈 │ └── 30-framework-spring.mdc # 框架级：Spring Boot 约定 ├── src/ └── README.md

文件名前面的数字是排序用的，Cursor 会按文件名顺序加载规则。00-放最通用的，10-放后端，20-放前端，这样 AI 在处理不同文件时能按优先级匹配。

关于触发模式，.mdc文件的 frontmatter 支持四种：

这里有个坑：如果你同时写了alwaysApply: true和globs，Cursor 会以alwaysApply为准，globs被忽略。所以想按文件类型生效，就不要写alwaysApply: true。

另外，用户级规则（账号通用）在 Cursor 设置里的 Rules for AI 中配置，比如“Always respond in 简体中文”。项目级规则优先级高于用户级，两者会合并，但项目级可以覆盖用户级。团队协作时，把项目级规则提交到 Git，新成员拉下来就自动生效，不用每个人手动配。

3. 可直接复制的 Rules 配置片段：后端、前端、接口文档三件套

这一节是全文的核心，给出可以直接复制到项目里的配置片段。每个片段都标注了文件路径和触发模式，你按自己的项目结构微调即可。

3.1 全局规则：.cursor/rules/00-global.mdc

这个文件放最通用的约束，比如中文回复、提交规范、禁止行为。

--- description: 全局通用规则，所有对话生效 alwaysApply: true --- ## 响应语言 - 始终使用简体中文回复用户，代码注释可以用英文但优先中文。 ## Git 操作 - 完成一项功能开发后，主动执行 commit。 - commit message 使用简洁中文，格式：`feat: 新增用户登录接口`。 - 不要在一个 commit 里混入多个不相关的修改。 ## 禁止行为 - 不允许在对话中执行 `npm run dev` 或 `mvn spring-boot:run` 启动项目。 - 不允许创建测试文档或临时说明文件。 - 不允许修改与当前任务无关的代码。 - 不允许使用未经验证的第三方依赖。

3.2 后端规则：.cursor/rules/10-backend.mdc

后端规则重点约束分层结构、返回格式、异常处理。这里给出一个 Spring Boot 项目的配置。

--- description: 后端开发规则，适用于 Java 和 Spring Boot 项目 globs: "src/main/java/**/*.java" --- ## 项目结构 - 按功能或领域划分目录，遵循关注点分离原则。 - Controller 层只做参数校验和路由，不写业务逻辑。 - Service 层写业务逻辑，Manager 层做数据聚合，Mapper 层做数据访问。 - 目录嵌套不超过 4 层。 ## 返回格式 所有接口统一返回以下结构，不允许自定义其他格式： ```json { "error": 0, "body": {}, "message": "success", "success": true }

• error为 0 表示成功，非 0 表示业务错误码。
• body为数据体，没有数据时返回空对象{}。
• message为提示信息，成功时固定为success。
• success为布尔值，与error == 0保持一致。

代码规范

• 每个方法必须写注释，说明功能、入参、返回值。
• 单个方法行数不超过 300 行。
• 使用描述性的变量名和函数名，禁止a、b、tmp这类命名。
• 异常必须捕获并转换为统一返回结构，不允许直接抛到 Controller。
• 优先使用项目已有的工具类和枚举，不重复造轮子。

生成代码前检查

• 生成任何业务代码前，先查看func.md文档，确认是否已有相关服务。
• 如果已有类似功能，优先扩展现有方法，而不是新建类。
• 新增服务后，同步更新func.md文档。

### 3.3 前端规则：`.cursor/rules/20-frontend.mdc` 前端规则约束技术栈和组件使用，避免 AI 引入不相关的库。 ```markdown --- description: 前端开发规则，适用于 Vue3 项目 globs: "src/**/*.vue,src/**/*.js" --- ## 技术栈 - 使用 Vue3 + Vant 框架，使用原生 JavaScript，不使用 TypeScript。 - 状态管理使用 Pinia，管理用户登录态和购物车数据。 - 所有后端调用必须走 `src/api` 目录下的 API 封装，不允许在页面里直接写 axios。 - 优先使用 Vant 现有组件，不重复实现。 ## 页面结构 - 页面组件嵌套不超过 3 层。 - 开发页面前先扫描 `README.md` 的项目结构，看是否有可复用组件或工具方法。 - 更新文件后同步更新 `README.md` 中的项目结构目录。 ## 限制 - 不允许在 Vue 页面中定义测试数据，所有数据必须来自后端服务或 mock 接口。 - 不允许创建测试用例，除非明确要求。 - 使用真实 UI 图片，不使用占位符图片。

3.4 接口文档规则：.cursor/rules/11-api-doc.mdc

接口文档规则强制 AI 在改接口时同步更新文档，这是团队协作中最容易被忽略的一环。

--- description: API 文档同步规则 globs: "src/main/java/**/controller/**/*.java" --- ## 文档同步要求 当生成或修改 API 接口时，以下变更必须同步更新 API 文档： - 入参结构变更 - 返回参数变更 - URL 地址变更 - 请求方式变更 ## 文档格式 每个接口文档包含以下部分： ### 基本信息 - 接口名称：简短描述 - 功能描述：详细业务用途 - 接口地址：/api/endpoint - 请求方式：GET/POST ### 请求参数 用 JSON 示例加表格说明，表格列：参数名、类型、必填、说明、示例值。 ### 响应参数 用 JSON 示例加表格说明，如果 body 是对象，列出所有子字段，格式为 `body.字段名`。 ## 注意 - 文档中的示例值必须真实可用，不允许写 `xxx` 或 `test`。 - 如果接口有分页，必须说明默认页码和每页数量。

3.5 框架级规则：.cursor/rules/30-framework-spring.mdc

框架级规则可以引用社区维护的规则库。比如 Spring Boot 的规则，可以参考awesome-cursor-rules-mdc项目里的配置，把常用的分层约定、注解使用规范复制进来。这里给一个精简版：

--- description: Spring Boot 框架约定 globs: "src/main/java/**/*.java" --- ## 注解使用 - Controller 使用 `@RestController`，不混用 `@Controller`。 - Service 实现类使用 `@Service`，接口不加注解。 - 依赖注入优先使用构造器注入，不使用 `@Autowired` 字段注入。 ## 配置管理 - 配置项统一放在 `application.yml`，不使用 `application.properties`。 - 敏感配置使用环境变量占位符 `${DB_PASSWORD}`，不硬编码。 ## 日志 - 使用 SLF4J，不使用 `System.out.println`。 - 日志级别：入口用 info，异常用 error，调试用 debug。

这些配置片段可以直接复制到你的项目里，按实际包名和目录调整globs即可。配好之后，Cursor 在生成代码时会自动读取这些规则，你不需要每次在对话里重复“用中文回复”“返回结构要统一”。

4. 验证 Rules 是否生效：用 VS Code 对照检查的完整步骤

配好 Rules 之后，怎么确认它真的生效了？很多人配完就不管了，结果 AI 行为没变化，以为是 Cursor 的 bug。其实大概率是规则文件没被读取，或者触发条件写错了。

下面是一套用 VS Code 对照验证的检查步骤，你可以跟着做一遍。

4.1 检查文件位置和命名

首先确认.cursor/rules/目录在项目根目录下，不是src/里面。用 VS Code 打开项目，在资源管理器里应该能看到：

.cursor/ rules/ 00-global.mdc 10-backend.mdc

如果看不到.cursor目录，可能是被隐藏了。在 VS Code 设置里搜索files.exclude，确认没有把.cursor排除掉。另外，.mdc文件的后缀必须是.mdc，不是.md，写错了 Cursor 不认。

4.2 检查 frontmatter 格式

打开一个.mdc文件，确认开头是三横线包裹的 frontmatter：

--- description: 后端开发规则 globs: "src/main/java/**/*.java" ---

注意globs的值要用引号包裹，多个 glob 用逗号分隔。如果globs写成了src/main/java/**/*.java但没加引号，YAML 解析可能出错，规则就不生效。

4.3 用 VS Code 的 Cursor 插件查看规则加载状态

Cursor 是基于 VS Code 的，如果你在 VS Code 里装了 Cursor 插件，可以在输出面板里看到规则加载日志。步骤：

1. 打开 VS Code，按Ctrl + Shift + U打开输出面板。
2. 在右上角下拉框选择Cursor或Cursor Rules。
3. 查看日志里是否有Loaded rule: 10-backend.mdc这样的信息。

如果没有日志，说明规则文件没被识别。检查文件是否在.cursor/rules/下，frontmatter 是否合法。

4.4 用实际对话验证规则生效

最直接的验证方式是开一个 Cursor 对话，让它生成一段代码，看是否符合规则。比如你的后端规则里写了“返回结构统一为 error/body/message/success”，那就输入：

帮我写一个查询用户信息的接口，返回用户 ID、用户名、邮箱。

如果规则生效，AI 生成的代码应该包含统一的返回结构，而不是直接返回User对象。如果它返回了User对象，说明规则没生效，回到 4.1 检查文件位置。

再比如全局规则里写了“始终使用简体中文回复”，如果 AI 用英文回复，说明00-global.mdc没被加载。检查alwaysApply: true是否写对。

4.5 用@手动引用验证 Manual 规则

如果你有规则设置了手动触发（不写alwaysApply，不写globs），需要在对话里用@引用。比如：

@10-backend 帮我写一个订单创建接口

如果引用后 AI 行为符合规则，说明 Manual 规则配置正确。如果引用后没反应，检查文件名是否写对，Cursor 里@后面跟的是文件名（不含.mdc后缀）。

4.6 常见验证失败的原因

验证通过后，把.cursor/rules/目录提交到 Git，团队其他成员拉下来就自动生效。新成员不需要手动配置，AI 行为就和团队规范一致了。

5. 本篇常见报错排查：401、local proxy failed、reading choices、OAuth 一次讲清

在配置 Cursor Rules 和接入模型服务的过程中，你可能会遇到一些报错。这一节把最常见的几类错误和排查方法列出来，对照真实报错信息定位问题。

5.1 401 Unauthorized：API Key 无效或未配置

报错信息通常长这样：

Error: 401 Unauthorized {"error":{"message":"Invalid API key provided","type":"invalid_request_error"}}

这个错误说明请求携带的 API Key 无效。排查步骤：

第一，检查 Key 是否复制完整。很多人在控制台复制 Key 时漏掉了开头或结尾的字符，导致鉴权失败。重新复制一次，确保没有多余空格。

第二，检查 Key 是否过期或被删除。登录控制台，在 API Keys 页面确认 Key 状态是 active。

第三，检查请求头格式。Base URL 和 Key 的配置要匹配，比如：

Base URL: https://taotoken.net/api API Key: sk-xxxxxxxxxxxxxxxx Model ID: claude-sonnet-4-20250514

如果你用的是 Claude Code 或 Cline 这类工具，配置项名称可能不同，但核心三件套不变：Base URL、API Key、Model ID。缺一个都会报 401。

5.2 local proxy failed：本地代理连接失败

报错信息：

Error: local proxy failed: connect ECONNREFUSED 127.0.0.1:7890

这个错误说明工具尝试连接本地代理端口，但端口没有服务在监听。常见原因是之前配过代理，后来关掉了，但配置还留在环境变量或工具设置里。

排查方法：检查系统环境变量HTTP_PROXY和HTTPS_PROXY，如果指向了一个不存在的端口，删掉或改成正确的。在 Cursor 设置里搜索proxy，确认没有开启不需要的代理配置。

如果你没有使用任何代理，直接把相关配置清空即可。TaoToken 的 API 地址是直连的，不需要额外代理。

5.3 reading choices：响应格式解析失败

报错信息：

Error: reading choices: unexpected end of JSON input

这个错误通常出现在流式响应场景。工具期望收到 OpenAI 格式的choices数组，但实际收到的响应不是标准格式，或者响应被截断了。

排查步骤：

第一，确认 Base URL 是否正确。有些工具默认拼接/v1/chat/completions，如果你的 Base URL 已经包含了/api，再拼/v1就会 404，返回 HTML 错误页，解析 JSON 时就会报reading choices。

第二，确认 Model ID 是否拼写正确。模型名写错时，部分服务会返回错误信息而不是标准响应，导致解析失败。

第三，检查网络是否稳定。流式响应中途断开也会导致 JSON 不完整。可以先用非流式模式测试，确认基础请求能通。

5.4 OAuth 相关报错：认证流程未完成

报错信息：

Error: OAuth authentication failed: invalid_grant

这个错误出现在使用 OAuth 登录的场景，比如 Claude Code 的账号授权。invalid_grant通常表示授权码已过期或被重复使用。

排查方法：重新发起 OAuth 流程，不要复用之前的授权链接。如果多次失败，检查系统时间是否准确，时间偏差过大会导致 token 校验失败。

如果你用的是 API Key 模式而不是 OAuth，这个错误不会出现。在 Claude Code 里，可以通过auth.json配置 API Key 模式，避免 OAuth 流程。auth.json的路径通常在~/.claude/auth.json，内容格式：

{ "apiKey": "sk-xxxxxxxxxxxxxxxx", "baseUrl": "https://taotoken.net/api" }

配置好后，Claude Code 会直接用 API Key 鉴权，不走 OAuth。

5.5 规则不生效但没有任何报错

这是最隐蔽的问题：没有报错，但 AI 就是不遵守规则。排查思路：

第一，确认.mdc文件的 frontmatter 是合法的 YAML。可以用在线 YAML 校验工具检查，常见错误是冒号后面没空格、引号不匹配。

第二，确认globs匹配到了当前编辑的文件。比如你写的是src/main/java/**/*.java，但当前文件在src/test/java/下，就不会匹配。

第三，确认没有多个规则文件冲突。比如00-global.mdc说“用中文回复”，10-backend.mdc说“用英文回复”，AI 会随机选一个。合并冲突规则即可。

第四，重启 Cursor。规则文件修改后，Cursor 有时不会热加载，重启后才会重新读取。

6. 把 Rules 变成团队资产：从个人配置到协作规范的落地建议

Rules 配好之后，怎么让它从“个人技巧”变成“团队资产”？这一节给几个落地建议。

第一，把.cursor/rules/目录提交到 Git，和代码一起版本管理。新成员克隆项目后，Cursor 自动读取规则，不需要口头传达“我们返回结构要统一”。规则变更走 PR review，和代码变更一样有记录。

第二，规则文件按职责拆分，不要一个文件塞所有内容。全局规则、后端规则、前端规则、接口文档规则分开，每个文件不超过 100 行。这样修改时影响范围可控，review 也清晰。

第三，定期清理过期规则。项目技术栈升级后，旧规则可能不再适用。比如从 Vue2 升级到 Vue3，前端规则里的选项式 API 约定就要删掉。建议每个季度 review 一次规则文件。

第四，给规则文件写注释，说明每条规则的背景。比如“返回结构统一为 error/body/message/success”这条，注释里写“前端统一按 error 字段判断成功失败，不要改”。这样后来的人知道为什么这么定，不会随手删掉。

第五，用@手动规则处理低频场景。比如代码重构规范、数据库迁移规范，不需要每次对话都生效，配成 Manual 规则，需要时@引用即可。这样避免规则文件过长，影响 AI 响应速度。

如果你在团队里推广 Cursor，建议先在一两个项目试点，把 Rules 配好，跑两周，收集反馈后再推广到其他项目。规则不是越多越好，而是越准越好。一条“返回结构统一”的规则，比十条“代码要优雅”的规则有用得多。

最后，如果你需要接入模型服务来配合 Cursor 使用，可以走 API Keys 页面创建 Key，接入文档里有各工具的配置示例。验证模型是否可用时，用模型对话页面发一条测试消息即可。长期做编码和 Agent 任务的话，Coding Plan 更适合高频使用场景。