Open Code 文档

主题

首页文档搜索

OpenCode 实战教程：从零搭建一个 Node.js API 服务 ​

📚 分类: AI 编程工具 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Windows / Linux 系统，能联网

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 安装并启动 OpenCode 这个 AI 编程助手
  • [ ] 使用自然语言让 AI 为你创建项目文件
  • [ ] 理解 OpenCode 的两种核心工作模式（Build & Plan）
  • [ ] 掌握 /init、/share 等 5 个最常用的 Slash 命令

最终效果 ​

你将拥有一个由 AI 辅助生成的、可运行的 Node.js + Express 项目，它包含一个返回 JSON 数据的 /hello 接口。整个过程，你只需要输入自然语言指令，无需手动编写任何代码。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
Node.js≥ 18.0node -v
npm≥ 9.0npm -v
Git≥ 2.30git --version

1. 安装 OpenCode ​

打开你的终端（Terminal），执行以下一键安装脚本：

bash
$ curl -fsSL https://opencode.ai/install | bash

💡 提示：这是最通用的安装方式。如果你使用的是 macOS，也可以用 brew install opencode 安装。

✅ 验证：安装完成后，运行以下命令检查版本：

bash
$ opencode --version
# 预期输出类似：
opencode version 1.1.19

如果你看到了类似 1.1.19 的版本号，说明 OpenCode 已成功安装。

第 1 步：创建项目目录并启动 OpenCode ​

🎯 目标：创建一个空的项目文件夹，并在这个文件夹中启动 OpenCode 的交互界面。

📝 操作：

  1. 首先，在终端创建一个新目录并进入：

    bash
    $ mkdir my-first-api && cd my-first-api

  2. 然后，在这个目录下启动 OpenCode：

    bash
    $ opencode

    ⚠️ 首次启动：如果你是第一次运行，系统会引导你进行基础配置。

    • 模型选择：在显示的模型列表中，选择带有 Free 标签的免费模型（例如 MiniMax M2.1 或 GLM-4.7）。这样你无需任何 API Key 即可开始使用。
    • 登录选项：选择“跳过登录”即可。

✅ 验证：启动成功后，你的终端界面会变成 OpenCode 的 TUI（终端用户界面），看起来像一个带有输入框的聊天窗口。顶部会显示模型信息和当前工作目录。

第 2 步：初始化项目（让 AI 了解你的项目） ​

🎯 目标：让 OpenCode 分析当前空目录，并生成一个项目配置文件 AGENTS.md，方便 AI 后续理解项目结构。

📝 操作：

在 OpenCode 的聊天输入框中，输入以下命令并回车：

/init

🤔 为什么要这样做？/init 命令会触发 OpenCode 扫描当前目录。它会创建一个 .opencode/ 文件夹（用来存储索引），并生成一个 AGENTS.md 文件。这个文件就像一份“项目说明书”，告诉 AI 这个项目是做什么的、代码结构如何，从而让 AI 的回答更精准。

✅ 验证： 在终端输入 ls -la（在 OpenCode 界面外），你应该能看到新生成的 .opencode/ 文件夹和 AGENTS.md 文件。

第 3 步：用自然语言创建你的第一个 API ​

🎯 目标：向 OpenCode 下达指令，让它自动为你创建项目文件、安装依赖，并生成一个可运行的 Express 服务。

📝 操作：

在 OpenCode 的聊天输入框中，输入以下自然语言指令并回车：

创建一个 Express.js 服务，支持 /hello 路由返回 JSON { message: 'Hello World' } ，并添加 README。

接下来，你会看到 OpenCode 开始“思考”并执行一系列操作：

  1. 初始化 npm 项目：它会自动执行 npm init -y。
  2. 安装依赖：它会自动安装 express 包。
  3. 创建文件：它会创建 index.js 和 README.md 文件，并写入代码。
  4. 解释过程：你可以在界面上看到 AI 每一步的操作日志。

✅ 验证： 当 OpenCode 显示任务完成时，在你的终端（OpenCode 界面外）运行以下命令来启动服务：

bash
$ node index.js

你应该会看到类似 服务已启动：http://localhost:3000 的输出。

然后，打开浏览器，访问 http://localhost:3000/hello，你应该能看到以下 JSON 输出：

json
{ "message": "Hello World" }

🎉 恭喜！ 你已经成功使用 AI 助手创建了一个后端 API 服务。

第 4 步：理解 Plan 和 Build 模式 ​

🎯 目标：了解 OpenCode 的两种核心工作模式，知道何时该用哪种。

🤔 为什么需要两种模式？ 想象一下，你让 AI 帮你改代码，但它可能改错了地方。Plan 模式就像一个“安全顾问”，它只提建议，不会直接动手。Build 模式则像一个“执行者”，它直接修改文件。

📝 操作：

  1. 在你的 OpenCode 聊天界面中，按下键盘上的 Tab 键。
  2. 你会看到界面顶部的模式指示器发生了变化。
  • Plan 模式：默认是“只读”的。当你提问时，AI 会提供详细的修改计划，但不会直接编辑你的文件。它适合用于代码审查、架构讨论或进行有风险的操作前先确认方案。
  • Build 模式：拥有完全权限。AI 可以直接创建、编辑、删除文件，并执行终端命令。这是你日常开发中最常用的模式。

💡 提示：在不确定 AI 会做什么的时候，先用 Plan 模式问一遍，确认方案无误后，再切换到 Build 模式让它执行。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 分享你的会话：在 OpenCode 中输入 /share，它会生成一个链接。你可以把这个链接发给同事，他们能直接看到你刚才和 AI 的整个对话过程，包括所有代码变更。
  2. 非交互式使用：你可以在终端直接运行命令，而不进入 TUI 界面：
    bash
    $ opencode -p "修复 index.js 中的拼写错误" -f json
    这在自动化脚本或 CI/CD 流程中非常有用。

常见问题 (FAQ) ​

Q1: 启动 OpenCode 时报错 command not found: opencode 怎么办？A: 这说明安装脚本没有将 OpenCode 添加到系统的 PATH 环境变量中。请尝试关闭并重新打开你的终端。如果问题依旧，可以尝试使用 npm 安装：npm install -g opencode-ai。

Q2: 运行 /init 后没有反应？A: 请确保你是在 OpenCode 的 TUI 聊天界面中输入的命令，而不是在你的系统终端里。/ 开头的命令是 OpenCode 的“Slash 命令”，只能在它的聊天窗口中使用。

Q3: 如何退出 OpenCode？A: 在聊天界面中输入 /exit 或 /quit，或者直接按 Ctrl + C。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 安装与启动：学会了使用一键脚本安装 OpenCode，并成功启动其终端交互界面。
  2. 项目初始化：掌握了 /init 命令，让 AI 能理解你的项目上下文。
  3. 自然语言编程：体验了用自然语言描述需求，让 AI 自动完成编码、安装依赖等完整工作流。
  4. 模式切换：理解了 Plan（安全规划）和 Build（直接执行）两种模式的用途和区别。

下一步 ​

如果你想继续深入，建议学习：

  • 📖 OpenCode 官方文档：深入学习所有 Slash 命令和 CLI 参数：https://opencode.ai/docs
  • 📖 oh-my-opencode 插件：了解如何将 OpenCode 升级为一个多智能体协作团队，处理更复杂的任务：GitHub 仓库

💡 练习任务：尝试让 OpenCode 为你刚才创建的 API 添加一个 /user/:name 路由，当访问 http://localhost:3000/user/张三 时，返回 { "name": "张三" }。这是巩固知识的最佳方式。

yaml

## 相关文档

- [使用 OpenCode 搭建私有 AI 编程助手实战教程](/docs/opencode-shi-zhan-jiao-cheng/shi-yong-opencode-da-jian-si-you-ai-bian-cheng-zhu-shou-shi-zhan-jiao-cheng.html)

Open Code 文档社区

© 2026 Open Code. All rights reserved.