From 5f4236a23d4b636f7aba1f3cbbf2ae6386482f56 Mon Sep 17 00:00:00 2001 From: sanbuphy Date: Sun, 8 Feb 2026 22:56:22 +0800 Subject: [PATCH] docs: update article titles and improve content for clarity and engagement refactor(config.mjs): update sidebar text for better user understanding docs(1.0-finding-great-idea): restructure content to focus on user willingness to pay docs(1.2-building-prototype): enhance content with practical guidance and AI coding tips docs(1.3-integrating-ai-capabilities): improve introduction to emphasize real-world value docs(appendix-b-common-errors): completely restructure as debugging guide with AI assistance docs(example0-1): simplify title for AI coding tools comparison docs(example0-2): shorten title for building website with AI agents docs(extra6): expand deployment guide with multiple platform comparisons docs(extra7): update AI coding tools configuration with additional providers --- docs/.vitepress/config.mjs | 4 +- .../stage-1/1.0-finding-great-idea/index.md | 283 ++++++---- .../stage-1/1.2-building-prototype/index.md | 24 +- .../1.3-integrating-ai-capabilities/index.md | 6 +- .../appendix-a-product-thinking/index.md | 2 +- .../vibe-coding-tools-snake-game-tutorial.md | 2 +- ...ebsite-with-ai-coding-and-design-agents.md | 2 +- .../stage-1/appendix-b-common-errors/index.md | 512 ++++++++++-------- ...s-it-and-how-to-deploy-web-applications.md | 247 +++++++-- ...e-principles-of-test-driven-development.md | 86 ++- 10 files changed, 755 insertions(+), 413 deletions(-) diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index eac64ab..dda959d 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -260,7 +260,7 @@ const productManagerSidebar = [ collapsed: false, items: [ { - text: '常见报错与排查方法', + text: '写代码时遇到错误怎么办', link: '/zh-cn/stage-1/appendix-b-common-errors/' }, { @@ -393,7 +393,7 @@ export default defineConfig({ link: '/zh-cn/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github' }, { - text: '后端五：Zeabur 部署', + text: '后端五：如何部署 Web 应用', link: '/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications' }, { diff --git a/docs/zh-cn/stage-1/1.0-finding-great-idea/index.md b/docs/zh-cn/stage-1/1.0-finding-great-idea/index.md index 20f82de..25c469e 100644 --- a/docs/zh-cn/stage-1/1.0-finding-great-idea/index.md +++ b/docs/zh-cn/stage-1/1.0-finding-great-idea/index.md @@ -1,6 +1,6 @@ --- -title: '找到好点子 - 从投资人的视角发现真需求' -description: '学习真格基金等顶级投资机构的案例分析方法，掌握从日常痛点中发现商业机会的系统方法论，把普通想法打磨成有潜力的产品概念。' +title: '找到好点子 - 从用户需求到有人买单' +description: '学习如何从日常痛点中发现商业机会，掌握需求分析的系统方法论，把普通想法打磨成用户愿意付费的产品概念。' --- -## B.1 页面显示空白或不加载 +# 写代码时遇到错误怎么办 -### 可能的原因 +## 本章导读 -页面一片空白是初学者最常遇到的问题之一。这通常是由 **JavaScript 错误导致代码执行中断** 引起的，一旦脚本执行出错，后续的渲染过程就会停止。此外，**资源文件路径错误** 也是常见原因，比如图片或样式表没找到。**网络问题** 也可能导致关键资源加载失败。最后，**渲染逻辑错误**（例如在数据还没加载回来时就尝试渲染）也会导致页面白屏。 + -### 排查步骤 +在 AI 时代，排查错误的方式已经变了。 -#### 第一步：检查浏览器控制台 +你不需要背下所有错误类型，不需要成为调试专家，甚至不需要理解错误是什么意思。 -浏览器自带的开发者工具是你最好的帮手。按下 F12（或右键点击页面选择“检查”），打开开发者工具。首先查看 **Console** 标签页，寻找红色的错误信息，这通常直接指向问题的根源。然后查看 **Network** 标签页，看看是否有变红的请求，这意味着资源加载失败了。 +你只需要学会一件事：怎么问 AI。 -#### 第二步：常见错误类型 +本章会教你一套从简单到进阶的排查流程： -**错误 1：Uncaught TypeError: Cannot read property 'X' of undefined** +1. 第一步：直接问：描述现象 + 截图，一句话提问 +2. 第二步：补充信息：如果解决不了，再打开 F12 补充关键信息 -这是最经典的错误。它意味着你试图访问一个不存在（undefined）对象的属性。例如，当用户信息还没加载回来，`user` 变量是 `undefined` 时，你却试图访问 `user.name`。 +掌握这套流程后，90% 的报错你都能自己解决。 -- **解决方案**：使用可选链操作符 `?.` 或者逻辑或 `||` 来设置默认值。例如 `const userName = user?.name || '默认值';`。或者使用 `if (user)` 进行判断，确保对象存在后再访问其属性。 + -**错误 2：Failed to load resource** +::: info 说明 +本章所有方法基于 Cursor/Trae/Claude 等 AI IDE 的实际使用经验，可直接应用于日常开发。 +::: -这个错误提示说明浏览器找不到你指定的文件。原因通常是**文件路径写错了**（比如把相对路径 `../` 写成了 `./`），或者**文件名大小写不匹配**（在某些系统中 `Image.png` 和 `image.png` 是两个文件），或者文件根本就**不存在于项目中**。仔细检查路径和文件名通常能解决问题。 +
+ + + +
-**错误 3：Maximum update depth exceeded** +## 1. 核心心法：截图问 AI -这个错误通常发生在 React 等框架中，意味着出现了**无限循环渲染**。常见原因是 `useEffect` 钩子缺少了依赖数组，或者在组件渲染过程中直接修改了状态，导致“渲染 -> 更新状态 -> 触发渲染”的死循环。 +::: warning 为什么这一章很重要？ -### 向 AI 寻求帮助的模板 +很多初学者遇到报错时的第一反应是： +- 慌张，开始瞎改代码 +- 花半小时搜索"xxx 错误怎么解决" +- 试图自己理解错误是什么意思 +- 自己 debug 到深夜 -如果你无法自己解决，可以尝试用下面的模板问 AI： +这些都是在浪费时间。 + +在 AI 时代，调试已经变成了一件很简单的事： ``` -我在开发一个[项目类型]，遇到了页面空白的问题。 - -问题描述： -- 页面 URL：[你的页面路径] -- 预期行为：[应该显示什么] -- 实际行为：[页面完全空白/部分空白] - -控制台错误信息： -[粘贴完整的错误信息] - -相关代码： -[粘贴相关代码片段] - -我已经尝试过的解决方法： -1. [列出你尝试过的方法] +看到报错 → 截图 → 问 AI → 按 AI 说的做 ``` ---- +你不需要理解错误，不需要会调试，甚至不需要知道问题出在哪里。 -## B.2 数据保存不成功 +你只需要学会怎么问。 -### 可能的原因 +::: -辛辛苦苦输入的数据保存不了？这可能是因为**异步操作没有正确处理**，代码没等数据保存完就执行了下一步。也可能是发送给服务器的**数据格式错误**，不符合 API 的要求。此外，**存储 API 使用不当**（比如 `localStorage` 只能存字符串）或者**权限/配额问题**也可能导致保存失败。 +### 1.1 最简单的提问方式 -### 排查步骤 +不需要复杂的模板，两种方式任选： -#### 检查数据存储方式 +**方式一：描述现象** -**使用 localStorage** +格式：刚才做了什么，现在出现了什么 -`localStorage` 是浏览器提供的本地存储，但它只能存储字符串。如果你直接存一个对象，它会被强制转成 `[object Object]` 这种无意义的字符串。 -**正确做法**是：在保存前使用 `JSON.stringify(data)` 将对象转为字符串，在读取后使用 `JSON.parse()` 将字符串转回对象。同时，建议用 `try...catch` 包裹代码，以处理可能的异常（比如存储空间已满）。 - -**使用状态管理** - -在 React 等框架中，状态更新往往是异步的。 -**常见的错误**是：发起保存请求后，直接用旧的状态数据去更新 UI，或者误以为 `setState` 是立即生效的。 -**正确做法**是：在异步请求成功返回后，使用服务器返回的最新数据来更新本地状态，确保前后端数据一致。 - -### 调试技巧 - -调试数据问题的最好办法是“打桩”。在数据保存流程的关键节点添加 `console.log`： - -1. 打印“准备保存的数据”，确认发出去的数据是对的； -2. 打印“数据类型”，确认格式没问题； -3. 打印“保存结果”，查看 API 或存储方法的返回值； -4. 最后尝试重新读取数据并打印，验证是否真的保存成功了。 - ---- - -## B.3 样式显示不正常 - -### 常见问题 - -#### 问题 1：样式完全不生效 - -如果你写了 CSS 但页面没反应，首先检查 **CSS 文件是否正确引入**，比如在 JS 文件中是否有 `import './styles.css'`。其次检查 **类名是否拼写正确**，HTML 中的 `class` 和 CSS 中的类名必须完全一致（包括大小写）。最后，可能是**样式被覆盖**了，使用开发者工具查看元素的样式来源，确认是否有优先级更高的样式覆盖了你的代码。 - -#### 问题 2：样式在开发环境正常，打包后失效 - -这种情况通常是因为**资源路径问题**或**样式隔离**。如果使用了打包工具，确保图片等资源的引用路径是正确的（通常建议用相对路径）。如果使用了 CSS Modules 或 Scoped CSS，要注意全局样式可能会被隔离，导致无法应用到某些组件上。 - -#### 问题 3：响应式布局失效 - -如果页面在手机上显示得很奇怪，首先检查 HTML 头部是否添加了 `` 标签，这是响应式布局的基础。其次检查 **媒体查询（Media Queries）** 的语法是否正确，以及断点设置是否合理。最后，确认是否混用了固定单位（px）和相对单位（rem/em/%），导致布局缺乏弹性。 - -### 向 AI 寻求帮助时提供 - -向 AI 咨询样式问题时，提供以下信息会很有帮助： - -- 问题元素的 HTML 结构代码。 -- 相关的 CSS 代码。 -- 浏览器开发者工具中“Computed”（计算样式）截图。 -- 你期望的效果描述，或者一张参考设计图。 - ---- - -## B.4 点击按钮没反应 - -### 排查步骤 - -#### 1. 检查事件绑定 - -首先确认事件是否真的绑定到了按钮上。在 React 中，应该是 `onClick={handleClick}`（注意驼峰命名）。 -**常见错误**包括：写成了 `onclick`（全小写）；或者写成了 `onClick={handleClick()}`，这样会导致函数在渲染时就立即执行，而不是在点击时执行。 - -#### 2. 检查事件处理函数 - -确认事件处理函数本身是否有问题。 -**调试方法**是：在函数的第一行加一个 `console.log('按钮被点击')`。如果点击没日志，说明绑定有问题；如果有日志但没效果，说明函数内部逻辑有问题。注意，如果函数是异步的（async），确保你正确处理了 `await`，并且捕获了可能出现的错误。 - -#### 3. 检查按钮状态 - -有时候按钮没反应是因为它处于 **disabled**（禁用）状态，或者被其他透明元素遮挡了。 -**最佳实践**是：在进行异步操作（如提交表单）时，手动设置按钮为 loading 状态并禁用点击，防止用户重复提交。操作结束后，记得恢复按钮状态。 - -### 调试方法 - -调试交互问题时，遵循“逐步定位”原则： - -1. 先看函数有没有被调用（console.log）。 -2. 再看函数内部的状态和变量是否正确。 -3. 最后逐步检查每一行代码的执行结果，直到找到断点。 - ---- - -## B.5 API 调用失败 - -### 常见错误类型 - -#### 错误 1：CORS（跨域）错误 - -当你看到 `Access to ... has been blocked by CORS policy` 时，说明浏览器的同源策略阻止了你的请求。 -**解决方案**：最彻底的方法是后端开启 CORS 支持。在开发环境中，也可以配置前端代理（Proxy）来绕过限制。如果是调用第三方 API，检查文档是否需要特定的请求头或 API Key。 - -#### 错误 2：401 Unauthorized / 403 Forbidden - -这通常是权限问题。 -**原因**可能是：API Key 没填或填错了；Token 过期了；或者你的账户没有权限访问这个接口。 -**检查**：仔细核对 API Key 配置，确认认证信息（Authorization Header）是否正确传递。 - -#### 错误 3：429 Too Many Requests - -这意味着你发送请求太频繁，触发了服务器的限流机制。 -**解决**：检查代码是否有死循环导致疯狂发请求。如果没有，考虑给请求添加节流（Throttle）或防抖（Debounce），或者使用缓存来减少不必要的重复请求。 - -#### 错误 4：500 Internal Server Error - -这是服务器端出错了，通常不是前端的问题。 -**解决**：检查你的请求参数格式是否符合文档要求，有时候参数不对会导致服务器崩溃。查看 API 返回的详细错误信息。如果确认参数没问题，那就需要联系 API 提供方了。 - -### API 调用最佳实践 - -编写 API 调用代码时，建议封装一个通用的 `callAPI` 函数。在这个函数中，统一处理 API Key 的添加、JSON 数据的转换、以及错误状态码的检查。如果响应状态码不是 2xx，应该抛出一个包含详细错误信息的 Error，以便在上层逻辑中捕获并提示用户。 - ---- - -## B.6 如何把报错信息有效地反馈给 AI - -### 完整的错误报告模板 - -为了让 AI 更快帮你解决问题，请使用这个结构化的提问模板： - -```markdown -## 问题描述 - -我在开发一个[项目类型]时遇到了问题。 - -### 上下文信息 - -- 项目类型：[待办清单应用/笔记应用/游戏等] -- 使用的工具：[Cursor/VSCode/Trae 等] -- 技术栈：[React/Vue/原生 JS 等] -- 我的学习阶段：[刚开始/有一定基础等] - -### 问题详细描述 - -**预期行为：** -[我想要实现什么功能] - -**实际行为：** -[实际发生了什么] -[有没有错误提示？具体内容是什么？] - -**复现步骤：** - -1. [第一步操作] -2. [第二步操作] -3. [问题出现的步骤] - -### 错误信息 - -**控制台错误：** -[粘贴完整的错误堆栈信息] - -**Network 错误（如果有）：** -[粘贴请求和响应的详细信息] - -### 相关代码 - -[粘贴你的代码，最好包含上下文] - -### 我已经尝试过的方法 - -1. [方法 1] - 结果：[成功/失败/没有变化] -2. [方法 2] - 结果：[成功/失败/没有变化] -3. [方法 3] - 结果：[成功/失败/没有变化] - -### 其他补充信息 - -- [任何你觉得可能相关的信息] -- [比如：这个问题是最近才出现的，之前正常] -- [或者：只在特定浏览器/设备上出现] +``` +刚才我修改了登录页面的代码，现在页面白屏了，怎么办？ ``` ---- +**方式二：截图** -## 快速诊断流程图 +直接截图当前页面或报错信息 -遇到问题不知所措？试着按这个流程走一遍： +``` +[截图] -1. **页面显示异常？** -> 是 -> 打开控制台看 Console 错误 (参考 B.1)。 -2. **点击没反应？** -> 是 -> 检查事件绑定和函数调用 (参考 B.4)。 -3. **数据不保存？** -> 是 -> 检查异步逻辑和存储方法 (参考 B.2)。 -4. **样式不对？** -> 是 -> 检查 CSS 引入和类名匹配 (参考 B.3)。 -5. **API 调用失败？** -> 是 -> 查看 Network 响应码和错误信息 (参考 B.5)。 -6. **以上都不是？** -> 使用完整模板向 AI 求助 (参考 B.6)。 +这个报错怎么解决？ +``` ---- +**最好的方式：描述 + 截图** -## 调试心态建议 +``` +刚才我修改了登录页面的代码，现在页面白屏了。 -最后，保持良好的心态至关重要。 -**不要慌张**，错误是编程学习的必经之路，资深开发者每天也会遇到无数 bug。 -**系统排查**，按照流程一步步缩小问题范围，不要像无头苍蝇一样乱试。 -**记录问题**，把解决过的 bug 记下来，下次再遇到就胸有成竹了。 -**善用 AI**，AI 是你 24 小时待命的结对编程伙伴，学会向它清晰地描述问题。 -**保持耐心**，有些 bug 确实很难缠，休息一下，换个思路，往往会有转机。 +[截图] ---- +怎么办？ +``` -## 还是不行？ +**记住：描述清楚上下文，加上截图，AI 能更快帮你解决问题。** -如果你试遍了所有方法还是不行： +### 1.2 如何把问题讲清楚 -1. **截图保存**：把错误信息、代码、界面都截图保存下来。 -2. **整理问题**：用上面的模板把问题整理清楚。 -3. **寻求帮助**：带着整理好的信息，向 AI、学习群或技术社区求助。 -4. **休息一下**：有时候离开屏幕，喝杯水，大脑后台会自动处理问题，回来后说不定就有灵感了。 +很多初学者知道要提问，但不知道怎么说。其实只需要讲清楚三件事： -**记住：每一个错误都是学习的机会，解决它的过程就是你变强的过程！** +**1. 刚才做了什么** + +``` +刚才我点击了保存按钮 +刚才我修改了登录页面的代码 +刚才我刷新了页面 +``` + +**2. 现在看到了什么** + +``` +现在页面是空白的 +现在按钮点了没反应 +现在显示报错信息 +``` + +**3. 想要达到什么效果** + +``` +我想让数据保存成功 +我想让页面正常显示 +我想让按钮点击后弹出提示 +``` + +**完整示例：** + +``` +刚才我点击了保存按钮，现在页面显示"保存失败"的报错。 + +[截图] + +我想让表单数据成功保存到数据库，该怎么办？ +``` + +**关键原则：** +- 用大白话描述，不用专业术语 +- 按时间顺序说：先做了什么，然后发生了什么 +- 把你的预期说出来，让 AI 知道你想要什么 + +## 2. 第一步：直接描述现象提问 + +遇到问题时，不要急着打开 F12。先直接描述现象，截图当前页面，丢给 AI 看看。 + +很多时候，AI 看到截图就能直接给出解决方案。 + +### 2.1 常见现象怎么描述 + +::: tip 直接描述即可 + +**页面白屏** +``` +页面打开是空白的，怎么办？ + +[截图] +``` + +**按钮点击没反应** +``` +点击这个按钮没反应，帮我看看。 + +[截图] +``` + +**数据保存不了** +``` +点了保存，数据没存上，怎么办？ + +[截图] +``` + +**样式显示不对** +``` +这个按钮位置偏了，怎么调整？ + +[截图] +``` + +**接口报错** +``` +调用接口报错了，帮我看看。 + +[截图] +``` + +::: + +### 2.2 如果 AI 直接解决了 + +恭喜你，问题解决了！按照 AI 说的修改即可。 + +### 2.3 如果 AI 说"需要更多信息" + +这时候才需要打开 F12，补充关键信息。往下看。 + +## 3. 第二步：补充关键信息 + +当 AI 说需要更多信息时，根据问题类型，打开 F12 截取对应的内容。 + +### 3.1 什么时候需要补充信息 + +AI 可能会这样回复： +- "请打开 Console 看看有没有报错" +- "截图 Network 面板给我看看" +- "需要看具体的错误信息" + +这时候，根据下面的指引补充截图。 + +### 3.2 补充 Console 信息（页面白屏/报错） + +::: tip 操作步骤 + +**第一步：按 F12 打开开发者工具** + +Mac 是 `Cmd+Option+I`，或者右键页面选"检查"。 + +**第二步：切换到 Console 标签页** + +**第三步：截图红色报错信息** + +**第四步：发给 AI** + +``` +Console 报错如下： + +[截图] +``` + +::: + +### 3.3 补充 Network 信息（数据问题/API 报错） + +::: tip 操作步骤 + +**第一步：按 F12 打开开发者工具** + +**第二步：切换到 Network 标签页** + +**第三步：重新操作一遍**（点保存/刷新页面） + +**第四步：找到对应请求，截图** + +- 看 URL 和状态码 +- 看 Payload（传的参数） +- 看 Response（返回结果） + +**第五步：发给 AI** + +``` +Network 信息如下： + +请求：[截图1] +参数：[截图2] +返回：[截图3] +``` + +::: + +### 3.4 补充 Elements 信息（样式问题） + +::: tip 操作步骤 + +**第一步：右键元素 → "检查"** + +开发者工具会自动定位到该元素。 + +**第二步：截图 Styles 面板** + +**第三步：发给 AI** + +``` +元素样式如下： + +[截图] +``` + +::: + +## 4. 第三步：迭代直到解决 + +### 4.1 低效的做法 + +这些做法会浪费你的时间： + +看到报错就慌张，开始瞎改代码 +花半小时搜索错误解决方案 +试图自己理解每个错误的意思 +一个人 debug 到深夜 + +### 4.2 高效的做法 + +按照这套流程来： + +先直接描述现象截图提问 +AI 说需要更多信息时，再打开 F12 补充 +按照建议修改代码 +改完后测试，如果问题还在就继续截图提问 + +## 5. 总结：完整流程 + +``` +遇到问题 + ↓ +直接描述现象 + 截图 + ↓ +丢给 AI："怎么办？" + ↓ +AI 直接解决？ + ↓ 是 +按 AI 说的做 + ↓ +测试是否解决 + ↓ + ↓ 否 / AI 需要更多信息 +打开 F12，补充关键信息 + ↓ +再发给 AI + ↓ +重复直到解决 +``` diff --git a/docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md b/docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md index 86a3c39..4b0624a 100644 --- a/docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md +++ b/docs/zh-cn/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md @@ -1,39 +1,177 @@ -# 扩展知识 6 - Zeabur 是什么，以及如何部署 Web 应用 +# 扩展知识 6 - 如何部署 Web 应用 -在本教程中，我们将介绍 Zeabur——一个用于部署 Web 服务的平台。它可以帮助我们快速完成从“写好代码”到“让别人可以在互联网上访问你的网站”的完整流程。 +在本教程中，我们将介绍如何将你的 Web 应用部署到互联网上，让其他人可以访问。我们会介绍三个常用的部署平台：**腾讯云 CloudBase**、**Vercel** 和 **Zeabur**，帮助你快速完成从"写好代码"到"让别人可以在互联网上访问你的网站"的完整流程。 -# 什么是“部署”？ +# 什么是"部署"？ -在开始之前，我们先弄清楚“部署（Deployment）”到底是什么意思。任何一个网站想要被外部用户访问，都必须有一个可以公开访问的网络地址（这个地址可以是 IP 地址，比如 123.45.67.89，也可以是域名，比如 [google.com](https://google.com/) 等）。但只有地址是不够的——你写好的网页代码（例如 HTML、CSS、JavaScript 文件，或者使用 React、Vue 等框架写的项目），以及相关的图片 / 视频资源，都必须“放”在一台 24 小时在线的服务器上，由它来响应网络请求，这样任何人的浏览器才能访问并下载这些资源。 +在开始之前，我们先弄清楚"部署（Deployment）"到底是什么意思。任何一个网站想要被外部用户访问，都必须有一个可以公开访问的网络地址（这个地址可以是 IP 地址，比如 123.45.67.89，也可以是域名，比如 [google.com](https://google.com/) 等）。但只有地址是不够的——你写好的网页代码（例如 HTML、CSS、JavaScript 文件，或者使用 React、Vue 等框架写的项目），以及相关的图片 / 视频资源，都必须"放"在一台 24 小时在线的服务器上，由它来响应网络请求，这样任何人的浏览器才能访问并下载这些资源。 ![](images/image1.png) 图片来源：https://www.hostinger.com/tutorials/what-is-cloud-hosting -把资源上传、配置好环境并让服务“跑起来”的整个过程，就被称为 **部署（Deployment）**。 +把资源上传、配置好环境并让服务"跑起来"的整个过程，就被称为 **部署（Deployment）**。 -简单来说：你在自己电脑上写好的网页，只要在本机启动程序，就只能通过本地地址在自己的浏览器里访问，因为这些代码只存在于你的硬盘上。“部署”就是把你的代码和资源转移到一台连接着公网的专业服务器上，并做好配置，让这台服务器知道“别人访问时我要怎么响应”——比如：当有人在浏览器中输入你的域名时，服务器会立刻找到对应的网页文件，把内容传回给对方的设备，从而让用户看到你的页面。 +简单来说：你在自己电脑上写好的网页，只要在本机启动程序，就只能通过本地地址在自己的浏览器里访问，因为这些代码只存在于你的硬盘上。"部署"就是把你的代码和资源转移到一台连接着公网的专业服务器上，并做好配置，让这台服务器知道"别人访问时我要怎么响应"——比如：当有人在浏览器中输入你的域名时，服务器会立刻找到对应的网页文件，把内容传回给对方的设备，从而让用户看到你的页面。 如果手动部署，一个项目往往需要好几个步骤，每一步都可能踩坑。常见关键步骤包括： 1. **服务器准备**：你需要先购买云服务器（比如阿里云、腾讯云、或 AWS EC2），选择服务器所在地区（如上海、新加坡）、配置（CPU、内存、磁盘大小等），还要学会如何远程连接服务器（例如通过 SSH 工具登录）。 ![](images/image2.png) -2. **环境配置**：Web 应用需要在特定“环境”中才能运行——例如运行 Node.js 项目必须先安装 Node.js；运行 Python 项目必须安装 Python 以及对应的第三方库。如果环境版本不匹配，程序就可能报错、无法启动。 +2. **环境配置**：Web 应用需要在特定"环境"中才能运行——例如运行 Node.js 项目必须先安装 Node.js；运行 Python 项目必须安装 Python 以及对应的第三方库。如果环境版本不匹配，程序就可能报错、无法启动。 3. **上传资源**：你需要把本地的代码和资源上传到服务器上，常用的方法包括 FTP 或 Git。如果项目体积比较大（比如包含视频文件），中途一旦断线，有时需要重新上传。 ![](images/image3.png) -4. **启动服务并测试**：上传完成后，你还需要在服务器上执行命令启动应用，并测试“分配的网络地址是否能访问”。如果访问不了，有可能是服务器防火墙没有放行对应端口（比如你的应用监听 3000 端口，但该端口被防火墙拦截），也可能是程序本身有 Bug，这时就需要查看服务器日志进行排查。 - > 💡 可以把端口理解为区分同一台设备上不同应用的“房间号”，而 IP 则是这台设备的“门牌号”。IP 和端口合在一起（IP:port），就可以精确定位到某一个网络服务。 -5. **维护与更新**：后续每次你修改代码，都要重新上传并重启服务。如果服务器宕机（例如断电、网络故障），还需要手动重启应用，有时还要额外配置“进程守护工具”，让程序在异常退出后自动拉起。 +4. **启动服务并测试**：上传完成后，你还需要在服务器上执行命令启动应用，并测试"分配的网络地址是否能访问"。如果访问不了，有可能是服务器防火墙没有放行对应端口（比如你的应用监听 3000 端口，但该端口被防火墙拦截），也可能是程序本身有 Bug，这时就需要查看服务器日志进行排查。 + > 💡 可以把端口理解为区分同一台设备上不同应用的"房间号"，而 IP 则是这台设备的"门牌号"。IP 和端口合在一起（IP:port），就可以精确定位到某一个网络服务。 +5. **维护与更新**：后续每次你修改代码，都要重新上传并重启服务。如果服务器宕机（例如断电、网络故障），还需要手动重启应用，有时还要额外配置"进程守护工具"，让程序在异常退出后自动拉起。 -像 Zeabur 这样的“低代码部署平台”，就是为了解决上述复杂问题而诞生的。它会帮你自动完成“买服务器、配环境、上传代码、启动服务、监控运行”等步骤。你只需要把自己的代码仓库（比如 GitHub 或 GitLab）连接到 Zeabur，它就会自动拉取代码、识别应用类型、配置对应的运行时环境，最后给你一个可以被任何人访问的公网地址。它甚至可以一键绑定你自己的域名（例如把 your-app.zeabur.app 改成 your-app.com）。 +像 CloudBase、Vercel、Zeabur 这样的"低代码部署平台"，就是为了解决上述复杂问题而诞生的。它们会帮你自动完成"买服务器、配环境、上传代码、启动服务、监控运行"等步骤。你只需要把自己的代码仓库（比如 GitHub 或 GitLab）连接到平台，或者直接上传代码，它就会自动拉取代码、识别应用类型、配置对应的运行时环境，最后给你一个可以被任何人访问的公网地址。它甚至可以一键绑定你自己的域名。 ![](images/image4.png) -接下来，我们会一步步演示如何使用 Zeabur，从“代码仓库”走到“公开可访问的网页”，全程不需要手写任何服务器命令。当然，你也可以使用 Vercel（同样有免费额度）来做类似的简单 Web 部署。不过，[Vercel](https://vercel.com/) 在部分网络环境下访问不太稳定，有兴趣的同学可以课后自行学习（操作也很简单：就是把 GitHub 项目连上即可）。 +接下来，我们会分别介绍这三个平台的特点和使用方法，帮助你选择最适合自己的部署方案。 -# 使用 Zeabur 部署 Dify +--- + +# 部署平台对比 + +| 平台 | 特点 | 适用场景 | 免费额度 | +|------|------|----------|----------| +| **腾讯云 CloudBase** | 国内访问速度快，与微信生态深度整合 | 国内用户为主、需要微信小程序支持的项目 | 有免费额度 | +| **Vercel** | 前端框架支持好，与 GitHub 集成紧密 | React/Vue/Next.js 等现代前端项目 | 有免费额度 | +| **Zeabur** | 支持多种语言和服务模板，配置灵活 | 需要部署多种服务（如 Dify、n8n）的复杂项目 | 每月约 5 美元免费额度 | + +--- + +# 1. 腾讯云 CloudBase + +腾讯云 CloudBase（云开发）是腾讯云提供的一站式后端云服务，特别适合国内开发者使用。它的优势在于： + +- **国内访问速度快**：服务器位于国内，访问延迟低 +- **微信生态整合**：可以方便地对接微信小程序、公众号 +- **一站式解决方案**：提供静态网站托管、云函数、数据库、存储等全套服务 +- **免费额度充足**：个人开发者有充足的免费资源额度 + +## 使用 CloudBase 部署 Web 应用 + +### 步骤 1：注册并登录 + +访问 [腾讯云 CloudBase 控制台](https://console.cloud.tencent.com/tcb)，使用微信或 QQ 登录。 + +### 步骤 2：创建环境 + +点击"新建环境"，选择一个环境名称（如 `my-web-app`）。 + +> ⚠️ **注意**：CloudBase 的免费体验版需要兑换码才能开通。你需要关注腾讯云 CloudBase 公众号，在公众号中输入"领取兑换码"获取免费体验版的兑换码，然后在创建环境时填写兑换码即可开通免费环境（免费试用期为 6 个月）。 + +### 步骤 3：开通静态网站托管 + +在环境管理页面，找到"静态网站托管"功能并开通。开通后你会获得一个默认的访问域名。 + +CloudBase 的静态网站托管提供多种部署方式，与 Zeabur 类似： + +- **本地项目上传**：直接从本地上传构建好的静态文件（HTML、CSS、JS 等） +- **模板部署**：使用预设模板快速创建项目，如 React Web 应用模板、Vue Web 应用模板 +- **Git 仓库部署**：支持从 GitHub 等代码仓库自动拉取代码并部署 + +### 步骤 4：部署代码 + +在静态网站托管页面，CloudBase 提供三种部署方式： + +**方式一：本地项目部署（本地项目上传）** +- 在控制台选择"本地项目部署" +- 直接上传构建好的静态文件（HTML、CSS、JS 等） +- 选择你本地构建好的项目文件夹（如 `dist` 或 `build` 目录） +- 等待上传完成即可访问 + +**方式二：模板部署** +- 使用预设模板快速创建项目 +- 支持 React Web 应用模板、Vue Web 应用模板等 +- 基于模板自动构建并部署 + +**方式三：Git 仓库部署** +- **Git 个人仓库部署**：绑定你的 GitHub 等个人代码仓库 +- **公开仓库部署**：支持从公开的 Git 仓库拉取代码 +- 配置自动构建命令（如 `npm run build`） +- 每次推送代码会自动重新部署 + +> 💡 **提示**：你也可以使用 CLI 工具进行部署： +> ```bash +> # 安装 CloudBase CLI +> npm install -g @cloudbase/cli +> # 登录 +> tcb login +> # 部署 +> tcb hosting deploy ./dist -e your-env-id +> ``` + +### 步骤 5：配置自定义域名（可选） + +在静态网站托管设置中，可以绑定你自己的域名，并申请免费的 HTTPS 证书。 + +--- + +# 2. Vercel + +Vercel 是全球最流行的前端部署平台之一，特别适合部署 React、Vue、Next.js 等现代前端框架项目。它的特点包括： + +- **与 GitHub 深度集成**：推送代码即自动部署 +- **自动预览**：每个 Pull Request 都会生成独立的预览链接 +- **全球 CDN**：网站自动分发到全球节点，访问速度快 +- **Serverless 函数**：支持在项目中编写后端 API + +> ⚠️ **注意**：Vercel 在部分网络环境下访问可能不太稳定，国内用户建议优先考虑 CloudBase。 + +## 使用 Vercel 部署 Web 应用 + +### 步骤 1：注册账号 + +访问 [Vercel 官网](https://vercel.com)，使用 GitHub 账号登录。 + +### 步骤 2：导入项目 + +1. 点击 "Add New Project" +2. 选择你要部署的 GitHub 仓库 +3. 如果没有看到想要的仓库，点击 "Adjust GitHub App Permissions" 授权访问 + +### 步骤 3：配置构建设置 + +Vercel 会自动识别项目类型并配置构建命令： + +| 框架 | 构建命令 | 输出目录 | +|------|----------|----------| +| React | `npm run build` | `build` | +| Vue | `npm run build` | `dist` | +| Next.js | `next build` | - | +| 纯 HTML | - | 项目根目录 | + +如果自动识别不正确，可以手动修改： +- **Build Command**: 构建命令，如 `npm run build` +- **Output Directory**: 构建输出目录，如 `dist` 或 `build` +- **Install Command**: 依赖安装命令，通常是 `npm install` + +### 步骤 4：部署 + +点击 "Deploy" 按钮，等待构建完成。构建成功后，你会获得一个 `xxx.vercel.app` 的域名。 + +### 步骤 5：自定义域名（可选） + +在项目设置中的 "Domains" 页面，可以添加你自己的域名。Vercel 会自动配置 HTTPS。 + +--- + +# 3. Zeabur + +Zeabur 是一个新兴的部署平台，特别适合需要部署多种服务的复杂项目。它的优势在于： + +- **服务模板丰富**：内置 Dify、n8n、数据库等多种服务模板 +- **支持多种部署方式**：GitHub、模板、Docker 镜像、本地项目等 +- **灵活的服务组合**：可以在一个项目中部署多个相互关联的服务 +- **按量计费**：用多少付多少，适合实验性项目 + +## 使用 Zeabur 部署 Dify 在之前的课程中，我们已经简单接触过 Dify。现在，我们可以通过 [Zeabur](https://zeabur.com/projects) 非常轻松地启动自己的 Dify 服务。首先打开 [控制台页面](https://zeabur.com/projects)，我们先看一下上面的各个区域。 @@ -46,7 +184,7 @@ 3. **Docs**：查看 Zeabur 的完整文档说明。 4. **Templates**：这里列出了所有内置的模板镜像。 -> 这里提到的“镜像（Image）”，可以理解为“包含代码和运行环境的压缩包”。当某个服务在一台服务器上成功跑起来之后，我们可以选择把“这套运行环境 + 代码”打包成镜像。之后，在任何新服务器上，只要把这个压缩包解压并运行，就不需要重新配置环境和代码，服务就能直接跑起来。 +> 这里提到的"镜像（Image）"，可以理解为"包含代码和运行环境的压缩包"。当某个服务在一台服务器上成功跑起来之后，我们可以选择把"这套运行环境 + 代码"打包成镜像。之后，在任何新服务器上，只要把这个压缩包解压并运行，就不需要重新配置环境和代码，服务就能直接跑起来。 在页面右上角，你还能看到自己的余额。默认情况下，每个月会有 5 美元左右的免费额度。关于细节计费规则暂时可以不用太在意，只需要知道：只要服务器在运行，就会消耗额度。 @@ -56,7 +194,7 @@ ![](images/image7.png) -现在我们来创建自己的 Dify 服务。首先，在 [控制台首页](https://zeabur.com/projects) 点击 “New Project”。 +现在我们来创建自己的 Dify 服务。首先，在 [控制台首页](https://zeabur.com/projects) 点击 "New Project"。 ![](images/image8.png) @@ -85,7 +223,7 @@ 7. **Cursor** 如果你安装了 Cursor（例如 Cursor IDE），可以通过这个入口将 Cursor 中的项目直接部署到 Zeabur。 -如果你想部署自己的 Dify 服务，推荐选择 **Template** 方式，然后在搜索框中输入 “dify”。可以看到很多由不同作者维护的版本，你可以任选其一（比如 v1.6.0 版本）。 +如果你想部署自己的 Dify 服务，推荐选择 **Template** 方式，然后在搜索框中输入 "dify"。可以看到很多由不同作者维护的版本，你可以任选其一（比如 v1.6.0 版本）。 ![](images/image15.png) @@ -93,9 +231,9 @@ ![](images/image16.png) -创建完成后，你会看到多个程序（服务）依次启动。需要耐心等待所有服务都进入“已启动”状态。（Dify 服务是由多个程序组成的，每个程序负责不同的功能，它们之间会相互协作。） +创建完成后，你会看到多个程序（服务）依次启动。需要耐心等待所有服务都进入"已启动"状态。（Dify 服务是由多个程序组成的，每个程序负责不同的功能，它们之间会相互协作。） -一般来说，你只需要点击左侧的 Dify 应用，就可以看到默认的访问入口地址。但在本例中，由于前面还套了一层 nginx，你需要点击 nginx 服务来获取最终访问地址。可以理解为：nginx 就是负责对外统一“收发请求”的主程序，它会把外部访问的地址分发给内部各个服务。点击左侧的 Nginx，在详情页中可以看到当前的服务地址，然后在浏览器里打开这个地址，等待服务完全启动。 +一般来说，你只需要点击左侧的 Dify 应用，就可以看到默认的访问入口地址。但在本例中，由于前面还套了一层 nginx，你需要点击 nginx 服务来获取最终访问地址。可以理解为：nginx 就是负责对外统一"收发请求"的主程序，它会把外部访问的地址分发给内部各个服务。点击左侧的 Nginx，在详情页中可以看到当前的服务地址，然后在浏览器里打开这个地址，等待服务完全启动。 ![](images/image17.png) @@ -107,21 +245,7 @@ ![](images/image19.png)![](images/image20.png) -# ⚠️ 如何停止和删除项目 - -由于启用服务器相关资源都会产生费用，我们在使用时一定要养成“及时关闭不用服务”的习惯，避免把每个月的免费额度消耗完。 - -如果要找到项目的管理入口，首先点击项目中的 “Settings” 选项。 - -![](images/image21.png) - -进入设置页面后，将页面拉到最下方，你会看到类似下面的界面： - -![](images/image22.png) - -你可以点击 “Suspend All Services” 来暂停所有服务以降低费用；如果服务出现问题，可以点击 “Restart All Services” 对全部服务进行重启。如果你确定不再需要这个项目，可以点击 “Delete Project” 将整个项目彻底删除。 - -# 使用 Zeabur 与 Trae 部署贪吃蛇游戏 +## 使用 Zeabur 与 Trae 部署贪吃蛇游戏 在本教程的下一个部分，我们会体验 Zeabur 的一些进阶用法。我们先用 Trae 生成一个贪吃蛇小游戏，再把它部署到 Zeabur 的服务器上，并配置一个可公开访问的链接，让任何人都可以打开你的游戏。 @@ -139,7 +263,7 @@ ![](images/image27.png) -点击左侧的 “Network” 选项，在页面中找到 “Public Address” 区域。点击 “Generate Domain”，即可生成一个对外访问地址，你可以输入任意喜欢的名称。 +点击左侧的 "Network" 选项，在页面中找到 "Public Address" 区域。点击 "Generate Domain"，即可生成一个对外访问地址，你可以输入任意喜欢的名称。 ![](images/image28.png) @@ -157,7 +281,7 @@ #### 重构为 React 架构 -在 Trae 中，你只需要向 Agent 说明：“帮我把这份代码重构成 React 架构”，就可以比较轻松地把原本基于 HTML 的结构重构成 React 项目。 +在 Trae 中，你只需要向 Agent 说明："帮我把这份代码重构成 React 架构"，就可以比较轻松地把原本基于 HTML 的结构重构成 React 项目。 ![](images/image32.png) @@ -165,36 +289,36 @@ 然而，在 Zeabur 上这样部署会失败——因为 Zeabur 只支持监听 8080 端口的应用。也就是说，如果想让 React 应用在 Zeabur 上正常运行，我们必须先把默认监听端口从 3000 改成 8080。 -要正确进行这一步配置，我们需要先弄清楚两个概念：什么是“端口（Port）”，以及“监听端口（Listening Port）”是什么意思。 +要正确进行这一步配置，我们需要先弄清楚两个概念：什么是"端口（Port）"，以及"监听端口（Listening Port）"是什么意思。 #### 什么是端口？ -> 在计算机网络中，端口可以理解为一个“逻辑通信端点”，用来区分同一台设备上运行的不同网络服务。简单类比的话，如果 IP 地址好比一个“门牌号”（例如 162.128.1.1），那端口号就像这栋楼里不同房间的“房间号”——每个房间对应一个服务（例如 Web 服务器、邮箱服务，或者你的 React 应用）。 +> 在计算机网络中，端口可以理解为一个"逻辑通信端点"，用来区分同一台设备上运行的不同网络服务。简单类比的话，如果 IP 地址好比一个"门牌号"（例如 162.128.1.1），那端口号就像这栋楼里不同房间的"房间号"——每个房间对应一个服务（例如 Web 服务器、邮箱服务，或者你的 React 应用）。 > > 端口号用 16 位整型表示，取值范围是 0 到 65535。 -如果不想记这些细节，可以简单理解：端口是构成“网络访问地址”的一个必要部分。 +如果不想记这些细节，可以简单理解：端口是构成"网络访问地址"的一个必要部分。 我们平时访问网站或 IP 地址时，通常不会手动加端口号，是因为 Web 的默认端口是 80 或 443（HTTPS）。大多数浏览器会自动使用这些标准端口。而对于一些特殊端口，比如 React 默认的 3000、Zeabur 要求的 8080，我们就必须在地址后面加上 `:3000` 或 `:8080` 才能访问到对应的内容。 -#### 什么是“监听端口号”？ +#### 什么是"监听端口号"？ -> “监听端口号”指的是某个程序在一台设备上主动“打开并监控”的端口。当一个应用设置了监听端口时，其实就是在告诉操作系统：“我会一直在这个端口上等待网络请求——只要有请求进来，就请转发给我。” +> "监听端口号"指的是某个程序在一台设备上主动"打开并监控"的端口。当一个应用设置了监听端口时，其实就是在告诉操作系统："我会一直在这个端口上等待网络请求——只要有请求进来，就请转发给我。" 再形象一点地理解：假设你的电脑是一栋写字楼，IP 地址是这栋楼的地址。楼里开了很多公司或部门，它们分别占用不同的房间，房间号就是端口号。 -当默认的 React 开发服务器启动时，它会“打开”某个房间的门，并安排“前台”在门口值班，这个房间号就是它的监听端口——3000。 +当默认的 React 开发服务器启动时，它会"打开"某个房间的门，并安排"前台"在门口值班，这个房间号就是它的监听端口——3000。 -同时，React 程序还会告诉这栋楼的“物业管理”（操作系统）：“我在 3000 号房间，请把所有寄给 3000 的信件（网络请求）都转给我。” +同时，React 程序还会告诉这栋楼的"物业管理"（操作系统）："我在 3000 号房间，请把所有寄给 3000 的信件（网络请求）都转给我。" -这样，当你访问 React 网站时，请求首先会到达这栋楼；物业看到请求要送到 3000 号房间，就会立刻把请求交给 React 的“前台”，由它来处理并返回结果——这就是访问 React 应用的过程。 +这样，当你访问 React 网站时，请求首先会到达这栋楼；物业看到请求要送到 3000 号房间，就会立刻把请求交给 React 的"前台"，由它来处理并返回结果——这就是访问 React 应用的过程。 当你在本地执行 `npm start`（本地启动 React 开发服务器的默认命令，也可以在 Vibe Coding 的 Agent 侧边栏中执行）时，React 开发服务器就会自动把监听端口设置为 3000。 -而 Zeabur 的平台设计决定了它只会“识别”监听 8080 端口的应用。如果你的 React 应用仍然使用默认的 3000 端口，Zeabur 就无法将请求正确转发给你的应用，最终导致部署失败。 +而 Zeabur 的平台设计决定了它只会"识别"监听 8080 端口的应用。如果你的 React 应用仍然使用默认的 3000 端口，Zeabur 就无法将请求正确转发给你的应用，最终导致部署失败。 #### 修改默认监听端口 -要把 React 默认监听端口（3000）改成 Zeabur 所要求的 8080，有很多做法。最简单的方式，就是直接在 Trae 里对 Agent 下指令：“请帮我把这个 React 项目的默认端口改为 8080。”Trae 就会帮你修改项目中对应的配置文件。修改完成后，你只需重新打包并按前面的方式上传到 Zeabur 即可。 +要把 React 默认监听端口（3000）改成 Zeabur 所要求的 8080，有很多做法。最简单的方式，就是直接在 Trae 里对 Agent 下指令："请帮我把这个 React 项目的默认端口改为 8080。"Trae 就会帮你修改项目中对应的配置文件。修改完成后，你只需重新打包并按前面的方式上传到 Zeabur 即可。 ![](images/image33.png) @@ -209,3 +333,36 @@ 对于其它需要修改端口号的程序，你也可以采用同样的思路：先改默认端口，再上传到 Zeabur 部署。至此，你已经掌握了将常见 Web 应用部署到服务器的基础技能。 你可以尝试让 Trae 帮你构建不同类型的应用，并把它们部署到 Zeabur 的默认服务器上。在后续课程中，我们还会学习如何把应用部署到你自己购买的云服务器上。 + +--- + +# ⚠️ 如何停止和删除项目（Zeabur） + +由于启用服务器相关资源都会产生费用，我们在使用时一定要养成"及时关闭不用服务"的习惯，避免把每个月的免费额度消耗完。 + +如果要找到项目的管理入口，首先点击项目中的 "Settings" 选项。 + +![](images/image21.png) + +进入设置页面后，将页面拉到最下方，你会看到类似下面的界面： + +![](images/image22.png) + +你可以点击 "Suspend All Services" 来暂停所有服务以降低费用；如果服务出现问题，可以点击 "Restart All Services" 对全部服务进行重启。如果你确定不再需要这个项目，可以点击 "Delete Project" 将整个项目彻底删除。 + +--- + +# 总结 + +在本教程中，我们介绍了三个常用的 Web 应用部署平台： + +1. **腾讯云 CloudBase**：适合国内用户，访问速度快，与微信生态整合好 +2. **Vercel**：适合现代前端框架项目，与 GitHub 集成紧密，全球 CDN 加速 +3. **Zeabur**：适合复杂项目，服务模板丰富，支持多种部署方式 + +选择哪个平台取决于你的具体需求： +- 如果主要面向国内用户，推荐 **CloudBase** +- 如果使用 React/Next.js 等框架，推荐 **Vercel** +- 如果需要部署 Dify、n8n 等服务，推荐 **Zeabur** + +无论选择哪个平台，部署的核心流程都是相似的：准备代码 → 选择平台 → 配置构建设置 → 部署上线。掌握这些技能后，你就可以将自己开发的应用分享给全世界了！ diff --git a/docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md b/docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md index 7f93d44..33a60d8 100644 --- a/docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md +++ b/docs/zh-cn/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md @@ -182,16 +182,62 @@ please help me configure and start Claude Code #### 使用 Kimi K2 作为后端（推荐） -https://platform.moonshot.cn/console/account +Kimi K2 是月之暗面（Moonshot AI）推出的新一代大语言模型，在代码理解和生成能力上表现出色。Kimi K2 支持超长上下文窗口（最高可达 200K tokens），能够轻松处理大型代码库和复杂项目。 -```Plain +**核心优势：** +- **超长上下文**：支持 200K 上下文窗口，可以一次性处理整个项目的代码 +- **代码能力强**：在代码生成、重构和调试方面表现优异 +- **中文理解好**：对中文编程需求的理解更加准确 +- **工具调用稳定**：支持稳定的函数调用和工具使用 + +**获取 API Key：** + +访问 https://platform.moonshot.cn/console/account 注册并获取 API Key。 + +**配置方法：** + +```Bash export ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic export ANTHROPIC_AUTH_TOKEN=sk-YOURKEY ``` +#### 使用 Minimax 作为后端（推荐） + +Minimax 是稀宇科技（MiniMax）推出的新一代大语言模型，在编程任务上表现优异。Minimax 模型以其出色的推理能力和代码生成质量而闻名，特别适合复杂的编程场景。 + +**核心优势：** +- **推理能力强**：在复杂逻辑推理和代码架构设计方面表现出色 +- **代码质量高**：生成的代码结构清晰、可读性好 +- **多语言支持**：支持多种编程语言的代码生成和转换 +- **响应速度快**：API 响应速度快，适合高频调用场景 + +**获取 API Key：** + +访问 https://platform.minimaxi.com/user-center/basic-information/interface-key 注册并获取 API Key。 + +**配置方法：** + +```Bash +export ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic +export ANTHROPIC_AUTH_TOKEN=YOUR_MINIMAX_API_KEY +export ANTHROPIC_MODEL=MiniMax-Text-01 +``` + #### 使用 DeepSeek 作为后端（推荐） -https://platform.deepseek.com/usage +DeepSeek 是深度求索推出的开源大语言模型，以其出色的代码能力和高性价比受到开发者欢迎。DeepSeek Coder 专门针对编程任务进行了优化训练。 + +**核心优势：** +- **代码能力突出**：在代码生成、代码理解和 Bug 修复方面表现优异 +- **开源可定制**：模型开源，可以根据需求进行微调 +- **性价比高**：API 价格相对较低，适合高频使用 +- **中文支持好**：对中文编程场景理解准确 + +**获取 API Key：** + +访问 https://platform.deepseek.com/usage 注册并获取 API Key。 + +**配置方法：** ```Bash export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic @@ -202,6 +248,28 @@ export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 ``` +#### 使用火山引擎 Coding Plan 作为后端（推荐） + +火山引擎（Volcano Engine）是字节跳动旗下的云服务平台，提供企业级的 AI 模型服务。火山引擎的 Coding Plan 专门为编程场景优化，提供稳定、高效的代码生成能力。 + +**核心优势：** +- **企业级稳定性**：提供服务等级协议（SLA），保障服务稳定性 +- **代码场景优化**：针对编程任务进行了专门优化 +- **丰富模型选择**：支持多种模型，包括 Doubao-pro、Doubao-lite 等 +- **国内访问快**：国内节点部署，访问速度快 + +**获取 API Key：** + +访问 https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey 注册并获取 API Key。 + +**配置方法：** + +```Bash +export ANTHROPIC_BASE_URL=https://ark.volces.com/api/anthropic +export ANTHROPIC_AUTH_TOKEN=YOUR_VOLCANO_API_KEY +export ANTHROPIC_MODEL=doubao-pro-32k +``` + #### 其他兼容 Anthropic 的 API Siliconflow： @@ -219,7 +287,7 @@ export ANTHROPIC_BASE_URL="https://dashscope.aliyuncs.com/apps/anthropic" export ANTHROPIC_API_KEY="YOUR_DASHSCOPE_API_KEY" ``` -#### 使用 Claude Code Route 作为后端（进阶用法） +::: details 使用 Claude Code Route 作为后端（进阶用法） 上面我们讲解了如何用 GLM 官方 API 替换 Claude Code 的 Anthropic 接口。接下来，我们来看一下 Claude Code Router 这个工具是如何让 Claude Code 适配更多模型 API 的。 @@ -227,7 +295,7 @@ export ANTHROPIC_API_KEY="YOUR_DASHSCOPE_API_KEY" ![](images/image16.png) -该工具还提供了方便的 UI/CLI 配置管理能力，并通过“转换器（converter）”适配不同平台的 API 格式。它支持 GitHub Actions 等自动化集成以及自定义扩展，解决了“单一模型无法覆盖所有场景”以及“频繁切换平台很麻烦”的问题，帮助用户更灵活、低成本地利用 AI 工具。 +该工具还提供了方便的 UI/CLI 配置管理能力，并通过"转换器（converter）"适配不同平台的 API 格式。它支持 GitHub Actions 等自动化集成以及自定义扩展，解决了"单一模型无法覆盖所有场景"以及"频繁切换平台很麻烦"的问题，帮助用户更灵活、低成本地利用 AI 工具。 ![](images/image17.png) @@ -251,13 +319,13 @@ npm install -g @musistudio/claude-code-router ![](images/image19.png) -此时点击 “Add Provider” 按钮，就会看到如下界面。你需要： +此时点击 "Add Provider" 按钮，就会看到如下界面。你需要： 1. 在 Name 中输入模型提供商的名字； 2. 在 API Full URL 中填写该提供商的 OpenAI 兼容接口地址； 3. 在 API Key 中填写对应平台的 API Key； -4. 在 Models 区域中填写模型名称，点击 “Add Model” 添加； -5. 最后点击 “Save” 保存配置。 +4. 在 Models 区域中填写模型名称，点击 "Add Model" 添加； +5. 最后点击 "Save" 保存配置。 （界面往下滚动还有很多高级选项，但目前你可以先忽略它们。） @@ -277,6 +345,8 @@ npm install -g @musistudio/claude-code-router ![](images/image24.png) +::: + #### Claude Code 的进阶用法 很多人最开始使用 Claude Code 时，只把它当成普通对话工具来用。但实际上，它内置了很多丰富的能力，能够让你使用起来更高效、灵活。下面是一些常见命令和用法示例：