跳到主要内容

🦞 我是如何基于 opencode 完成 ESP32 智能龙虾缸监控系统开发的

· 阅读需 7 分钟

前言

作为一个喜欢折腾的 DIY 爱好者,我一直想给我的小龙虾缸加一套智能监控系统。最近,我用了 opencode —— 一个强大的 AI 编程助手,竟然用不到 2 小时就搞定了!

今天就分享我是如何通过聊天式交互完成整个开发的。


项目背景

我的小龙虾缸需要:

  • 实时监测水温和空气温湿度
  • 根据水温自动控制水泵(降温/循环)
  • 能随时查看数据状态
  • 成本要低(不想买几百块的专业设备)

硬件清单

组件价格说明
ESP32 开发板¥30主控板
DS18B20 温度传感器¥5水温检测
DHT11 温湿度传感器¥3空气温湿度
5V 水泵模块¥15水循环控制
继电器模块¥8控制水泵
OLED 屏幕 (0.96寸)¥12本地显示
杜邦线若干¥5连接线

总成本:约 ¥78


传统开发 vs opencode 开发

如果不用 opencode,我需要:

  1. 查阅资料(2-3 小时)

    • ESP32 引脚定义
    • DS18B20 和 DHT11 的库使用方法
    • Web 服务器搭建教程
    • OLED 屏幕驱动
  2. 编写代码(4-6 小时)

    • 初始化各种传感器
    • WiFi 连接和配置
    • HTTP 服务器和路由
    • Web 界面(HTML/CSS/JS)
    • 自动控制逻辑
  3. 调试排错(1-2 小时)

    • 传感器读取失败
    • WiFi 连接不稳定
    • Web 界面无法访问

总时间:7-11 小时

用 opencode,我只花了 2 小时!


对话式开发全流程

第 1 次对话 - 项目框架

我:

我要开发一个 ESP32 智能龙虾缸监控系统,需要以下功能:
1. 使用 DS18B20 测量水温
2. 使用 DHT11 测量空气温湿度
3. 控制一个 5V 水泵(通过继电器)
4. 提供 Web 管理界面,可以查看数据和手动控制水泵
5. 使用 OLED 屏幕显示实时数据
请帮我生成完整的 PlatformIO 项目配置和代码

opencode: 好的,我来帮你生成完整的代码。这个项目将使用:

  • OneWire 和 DallasTemperature(DS18B20)
  • DHT 库(DHT11)
  • Adafruit_SSD1306(OLED)
  • ESPAsyncWebServer(Web 服务器)

📝 生成文件:

  • platformio.ini - 项目配置
  • src/main.cpp - 主程序代码
  • data/index.html - Web 界面

第 2 次对话 - 添加 WiFi 配置

我:

上面的代码不错,但我想要一个配置模式。首次启动时创建 AP 热点 "Lobster_Config",访问 192.168.4.1 可以配置 WiFi 信息。配置成功后保存到 SPIFFS,重启后自动连接。

opencode: 好的,我来添加 WiFi 配置功能。这将包括:

  • WiFiManager 类实现配置逻辑
  • 配置 Web 页面 HTML/CSS/JS
  • SPIFFS 文件系统初始化

⚠️ 注意:首次启动后连接 "Lobster_Config" 热点配置 WiFi。


第 3 次对话 - 自动控制逻辑

我:

我需要根据水温自动控制水泵。规则如下:
- 水温 > 28°C 时,水泵开启(每 10 分钟工作 5 分钟)
- 水温 < 24°C 时,水泵关闭
- 其他温度,水泵每 30 分钟工作 5 分钟

opencode: 好的,我来添加智能温控逻辑:

  • 温度阈值配置
  • 定时器实现
  • 状态机控制水泵开关

💡 智能策略:高温时增加水泵工作时间,低温时节省能源。


第 4 次对话 - 优化 Web 界面

我:

Web 界面需要更美观一些,要求:
1. 深色主题,现代化 UI
2. 实时数据更新(WebSocket 或轮询)
3. 显示历史数据图表(使用 Chart.js)
4. 移动端适配
5. 添加系统设置页面(修改阈值、工作时间等)

opencode: 好的,我来重新设计整个 Web 界面:

  • 响应式 HTML/CSS(深色主题)
  • Chart.js 图表集成
  • RESTful API 设计
  • 设置表单和验证

🎨 界面预览:现代化设计,支持手机和电脑访问。


硬件接线

根据生成的代码,接线非常清晰:

ESP32 引脚分配:
GPIO 4 → DS18B20 数据引脚
GPIO 5 → DHT11 数据引脚
GPIO 16 → 继电器控制引脚
GPIO 21 → OLED SDA
GPIO 22 → OLED SCL

关键注意事项:

  • ✅ DS18B20 需要 4.7kΩ 上拉电阻
  • ✅ 共地(所有 GND 连在一起)
  • ✅ 继电器接 VIN(5V),传感器接 3V3

使用体验

首次启动

=== Lobster Monitor System ===
WiFi Config AP: Lobster_Config
Config URL: http://192.168.4.1
Waiting for configuration...
  1. 连接 "Lobster_Config" 热点
  2. 浏览器访问 192.168.4.1
  3. 输入家庭 WiFi 密码
  4. 保存并重启

正常运行

Connecting to WiFi...
Connected! IP: 192.168.31.45
Starting HTTP server...
OLED initialized
Sensors ready

访问 Web 界面 http://192.168.31.45

  • 📊 实时数据图表
  • 🎛️ 手动控制水泵
  • ⚙️ 修改阈值设置
  • 📱 手机完美适配

遇到的坑

坑 1:DS18B20 总是返回 -127°C

现象: 水温传感器读取失败

解决对话:

我:DS18B20 总是返回 -127°C,这是我的接线代码,请帮我看看

opencode:看到问题了。DS18B20 需要 4.7kΩ 上拉电阻连接到 3V3,
否则无法正常通信。另外检查:
1. 确认 DAT 引脚连接到 GPIO 4
2. 确认 VCC 接 3V3(不是 5V)
3. 确认共地

结果: 加上拉电阻后立即正常。


坑 2:Web 界面刷新很慢

现象: 数据更新需要手动刷新页面

解决对话:

我:Web 界面数据刷新太慢,改用 WebSocket 实时推送

opencode:好的,我来添加 WebSocket 服务器端和客户端代码,
实现实时数据推送,无需手动刷新。

结果: 数据实时更新,体验丝滑。


坑 3:WiFi 经常断线

现象: 运行一段时间后 Web 界面无法访问

解决对话:

我:WiFi 连接不稳定,请添加断线重连机制

opencode:好的,我来添加自动重连逻辑,定期检查连接状态,
断线后自动重新连接。

结果: 稳定运行 24 小时无断线。


对话技巧总结

✅ 正确做法

1. 逐步添加功能

❌ 一次性描述所有需求
✅ 先生成基础框架,再逐步添加功能

2. 描述问题时提供上下文

❌ 代码报错了,帮我看看
✅ 编译时报错 "undefined reference to 'setup()'",这是 main.cpp

3. 明确告知技术栈

✅ 使用 PlatformIO + ESP32 + Arduino 框架
✅ 使用 AsyncWebServer 库(更好的并发性能)

❌ 避免踩坑

1. 不要一次性描述所有需求

  • AI 可能遗漏细节
  • 代码生成质量下降
  • 后续修改成本高

2. 不要忽略错误信息

  • 具体的错误信息能帮助 AI 快速定位
  • 提供代码片段让 AI 上下文更清晰

最终成果

功能清单

  • ✅ OLED 屏幕显示水温、气温、湿度
  • ✅ Web 界面实时数据更新
  • ✅ 水温 > 28°C 自动开启水泵
  • ✅ 水温 < 24°C 自动关闭水泵
  • ✅ 手动控制水泵
  • ✅ 历史数据图表
  • ✅ 阈值设置页面
  • ✅ WiFi 自动重连

代码质量

  • ✅ 错误处理完善(传感器读取失败时提示)
  • ✅ 内存使用合理(FreeHeap > 50KB)
  • ✅ SPIFFS 文件系统正常读写
  • ✅ 代码注释清晰,易于二次修改

效率对比

方面传统开发使用 opencode提升
代码编写4-6 小时30 分钟8-12倍
查阅资料2-3 小时0 分钟无限
调试排错1-2 小时30 分钟2-4倍
总时间7-11 小时2 小时3.5-5.5倍

总结

通过 opencode,我体验到了对话式编程的强大之处:

  1. 🚀 极速开发:2 小时完成传统开发 7-11 小时的工作量
  2. 💬 自然交互:用中文描述需求,无需懂复杂语法
  3. 🔄 渐进迭代:分步添加功能,边写边测试
  4. 🐛 高效调试:遇到问题直接描述,AI 立即给出解决方案
  5. 📚 学习赋能:通过生成的代码理解开发流程

最重要的是:我把节省下来的时间,花在更多有趣的 DIY 项目上!


下一步计划

基于这次成功经验,我打算:

  • 📸 添加摄像头监控(用 opencode 生成图像采集代码)
  • 📈 数据上传到云端(用 opencode 集成 MQTT)
  • 🤖 语音控制水泵(用 opencode 集成语音识别)
  • 📱 开发移动 App(用 opencode 生成 Flutter 代码)

如果你也想试试,不妨从简单的温湿度监测开始,让 opencode 帮你快速实现! 🦞

用「道法术器」理解 AI / LLM / OpenClaw

· 阅读需 4 分钟

可以用四个问题理解:

为什么龙虾能帮我们做事 → 如何让龙虾做事 → 怎么让龙虾做好事情 → 有哪些好用的工具

对应:

道(原理) → 法(方法) → 术(技巧) → 器(工具)


核心笔记

  • 道(原理):AI 能思考、写代码、用工具的三种能力
  • 法(方法):给 AI 清晰的任务流程和规则
  • 术(技巧):用清晰指令和拆分任务与 AI 沟通
  • 器(工具):AI 工具、技术环境、工具系统

学完你能做什么

  • 理解 AI 为什么能帮你做事
  • 学会如何让 AI 执行复杂任务
  • 掌握与 AI 高效沟通的技巧
  • 选择合适的工具组合提升效率

一、道(原理):为什么龙虾能帮我们做事

道(原理)- AI能思考、写代码、用工具的三种能力

"道"是底层原理。

龙虾之所以能完成任务,是因为它有三种能力:

1. 会写代码

龙虾学过大量代码,可以:

  • 写程序
  • 修改程序
  • 生成脚本

2. 会思考

龙虾可以:

  • 分析问题
  • 规划步骤
  • 按步骤完成任务

例如:

读取数据 → 分析 → 生成报告

3. 会用工具

龙虾可以调用工具:

  • 读写文件
  • 上网查询
  • 调用 API
  • 运行代码

所以龙虾不只是聊天工具,而是:

能思考、写代码、用工具的数字助手。

这就是 道(原理)


二、法(方法):如何让龙虾做事

法(方法)- 给AI清晰的任务流程和规则

"法"是 方法和做法

简单说就是:

给龙虾设计一套做事的方法。

例如:

分析 CSV:

  1. 读取数据
  2. 统计指标
  3. 生成图表
  4. 输出总结

这就是一套 完成任务的方法

在 AI 里,本质就是:

把任务拆成一个清晰的工作流程。

这就是 法(方法)


三、术(技巧):怎么让龙虾做好事情

术(技巧)- 用清晰指令和拆分任务与AI沟通

"术"是 使用技巧

例如:

写清晰的指令

坏指令:

分析数据

好指令:

读取 data.csv
统计平均值
生成图表
输出总结

或者:

把复杂任务拆成步骤。

同样一只龙虾,有的人用得很好,有的人用得很乱,差别往往就在这些 使用技巧

这就是 术(技巧)


四、器(工具):有哪些好用的工具

器(工具)- AI工具、技术环境、工具系统

"器"就是 工具本身

例如:

AI 工具

  • ChatGPT
  • Claude
  • OpenClaw

技术环境

  • Python
  • Node.js
  • Docker

工具系统

  • 文件系统
  • API
  • 搜索引擎
  • 自动脚本

这些工具,就是龙虾干活用的 钳子和爪子

这就是 器(工具)


一句话总结

层级含义AI里的意思
原理龙虾为什么能做事
方法如何设计龙虾做事的方法
技巧如何更好地使用龙虾
工具使用哪些工具

整体逻辑:

龙虾有能力(道) → 给龙虾方法(法) → 用技巧沟通(术) → 借助工具完成(器)


高手成长路径

善器 → 熟术 → 会法 → 懂道

先会用工具,再掌握技巧,然后理解方法,最后理解原理。


本课小结

用「道法术器」的框架理解 AI,可以帮助你:

  1. 道(原理):理解 AI 为什么能帮你做事(会思考、写代码、用工具)
  2. 法(方法):学会如何给 AI 安排任务流程
  3. 术(技巧):掌握与 AI 高效沟通的技巧(清晰指令、拆分任务)
  4. 器(工具):选择合适的工具组合

从善器开始,逐步成长到懂道,成为 AI 编程高手!

从看不起到追不上:理性看待 OpenCode 和 Agent 时代

· 阅读需 3 分钟

对立观点

最近 OpenCode、OpenCloud、低代码、大模型 Agent 这些技术在网上争议特别大。

我发现一个特别有意思的现象:

不懂技术的业务同学、非技术人员,觉得这些东西特别牛,恨不得马上上手,说不学就要被时代淘汰;

但很多一线程序员、技术人,反而觉得这就是伪命题,说有这功夫我直接手写代码不就行了。

一句话总结

既不要过度神化,也不要轻易否定,保持中立,理性看待。

核心笔记

  • 所有新技术的发展,都逃不开"看不起 → 看不清 → 追不上"的规律
  • 算法最终属于全人类,工程能力才是拉开差距的核心
  • Agent 不是简单的文字生成,而是复杂的系统工程
  • 90% 的程序员依然靠 CRUD 吃饭,这是最真实的行业现状
  • 技术发展永远比想象得更快

从火热到回归,再到新生

代码工程

最开始大模型刚出来的时候,大家一阵火热,热度很快又下去了。

直到 OpenCode、OpenCloud 这些工具出现,才重新回到大众视野。

为什么?因为它真正降低了门槛,让不会写代码的普通人,也能用上大模型、用上 Agent。

这个世界本来就是,不会编程的人,远远多于程序员。

所以这波浪潮,本质上是技术下沉,服务大多数人。

算法开源,工程为王

这里有一个很重要的观点:

算法,最终是属于全人类的。

未来大语言模型一定会越来越开源、越来越平民化,大家能用的模型能力差距会越来越小。

到最后,真正拉开差距、决定胜负的核心,就是工程能力,就是架构设计。

Agent 的复杂程度,远超想象

AI Agent 体系

很多程序员一开始也不屑一顾,觉得 Agent 不就是会聊天、词语接龙吗?

但我真正深入研究之后发现,比想象中难太多了。

它不是简单的文字生成,而是把大模型的推理能力、工具调用、记忆机制、SOP 流程、各种设计模式、回调机制全部整合在一起的复杂工程。

你去看现在主流的 OpenCode 源码就会发现,很多普通程序员已经看不懂了,跟我们平时写的 CRUD 完全不是一个层次。

90% 程序员的现实

其实大家想想,过去很多人看不起 CRUD,不也是这样吗?

但我们必须清醒:

哪怕现在技术卷成这样,行业里 90% 的程序员,依然是靠写业务代码、CRUD 吃饭。

这就是最真实的行业现状。

技术发展的必然趋势

未来,随着大模型和 Agent 真正走向工程化、规模化,系统会越来越复杂,代码量会越来越庞大。

人的精力、脑容量、学习速度都是有限的。

等到全球几十亿人、成千上万的工程一起迭代的时候,你可能连系统的全貌都再也看不懂了。

给你的建议

所以我给大家的建议非常实在:

不盲目追捧,也不傲慢抵触。

踏踏实实跟着 Agent、跟着新技术的方向走,保持学习,保持关注,千万别让自己真正掉队。

因为技术的发展,永远比我们想象得更快、更超出预期。

一句话总结

保持学习,理性看待,别让自己掉队。


本文观点仅供参考,欢迎在评论区交流讨论。

AI 编程的 10 个实用技巧

· 阅读需 2 分钟

分享 10 个实用的 AI 编程技巧,帮助你更高效地使用 AI 工具。

一句话总结

掌握这些技巧,让 AI 编程效率提升 10 倍。

核心笔记

  • 明确的需求描述是关键
  • 分步骤处理复杂任务
  • 始终验证 AI 生成的代码
  • 建立自己的代码模板库

学完你能做什么

应用这些技巧后,你将能够:

  • 更准确地描述编程需求
  • 获得更高质量的 AI 代码
  • 减少调试和修复的时间
  • 建立高效的开发工作流

你现在的困境

  • AI 给的代码经常跑不通
  • 不太清楚如何跟 AI 描述需求
  • 浪费时间在不断追问和修改

什么时候用这一招

  • 使用 AI 辅助开发时
  • 需要快速原型开发时
  • 遇到陌生技术领域时

核心思路

AI 编程的本质是"人机协作",你需要做的是:

  1. 清晰地表达意图
  2. 合理地拆解任务
  3. 严格地验证结果

跟我做

技巧 1:用结构化方式描述需求

❌ 不好的描述: "写个登录功能"

✅ 好的描述: "帮我写一个登录功能,要求:

  • 支持邮箱和手机号两种方式
  • 密码需要加密存储
  • 添加表单验证
  • 返回 JWT token"

技巧 2:分步骤处理复杂任务

一次只做一件事:

  1. 先写接口定义
  2. 再写数据模型
  3. 然后写 API 路由
  4. 最后写前端组件

技巧 3:验证 AI 生成的代码

检查清单:

  • 语法是否正确
  • 逻辑是否合理
  • 是否符合项目规范
  • 有无安全风险

技巧 4:保持代码可读性

要求 AI:

  • 使用有意义的变量名
  • 添加必要的注释
  • 拆分过长的函数
  • 遵循一致的代码风格

检查点

✔ 能清晰描述编程需求 ✔ 会拆分复杂任务 ✔ 知道如何验证 AI 代码 ✔ 有自己的代码库

踩坑提醒

问题: AI 生成的代码有 bug 原因: 需求描述不够清晰 解决: 提供更多上下文和约束条件

问题: AI 代码风格不一致 原因: 没有明确代码规范 解决: 提供代码示例和风格指南

本课小结

AI 是你的编程伙伴,不是替代者。掌握正确的协作方式,才能发挥最大价值。

2 小时从零部署个人网站到 GitHub Pages

· 阅读需 5 分钟

从零开始,在 2 小时内部署你的个人网站到 GitHub Pages,完全免费!

一句话总结

跟着我一步步操作,2 小时内搞定个人网站部署,适合完全小白的你。

核心笔记

  • 注册 GitHub 账户
  • 创建 GitHub Pages 仓库
  • 使用 OpenCode 创建项目
  • 配置 glm-4.7 模型
  • 编写和发布页面

学完你能做什么

完成本教程后,你将能够:

  • 拥有属于自己的个人网站
  • 使用 AI 辅助编程
  • 掌握 GitHub Pages 部署流程
  • 学会自然语言编程

你现在的困境

  • 没有编程基础,不知道如何开始
  • 想要个人网站但不知如何部署
  • 看到各种教程无从下手
  • 害怕操作复杂,怕出错

什么时候用这一招

  • 想要搭建个人博客或作品集
  • 需要学习网站部署流程
  • 想要实践 AI 编程
  • 完全零基础,需要详细教程

核心思路

GitHub Pages 提供免费的静态网站托管服务,我们只需要:

  1. 注册 GitHub 账户
  2. 创建一个仓库
  3. 使用 OpenCode 生成网站代码
  4. 推送代码到 GitHub,自动部署

跟我做

步骤 1:注册 GitHub 账户(5 分钟)

  1. 访问 https://github.com
  2. 点击右上角的"Sign up"按钮
  3. 选择注册方式:
    • 邮箱注册
    • Google 账号登录
  4. 填写用户名(这个会出现在你的网站地址中)
  5. 完成邮箱验证

注意: 记住你的用户名,后续会用到!

步骤 2:安装和配置 OpenCode(20 分钟)

2.1 下载 OpenCode

访问 OpenCode 官网下载并安装最新版本。

2.2 配置 glm-4.7 模型

  1. 打开 OpenCode
  2. 进入设置 → 模型配置
  3. 添加 glm-4.7 模型:
    • 模型名称:glm-4.7
    • API 地址:根据实际情况填写
    • 模型版本:最新稳定版

2.3 先看 Start 教程

在 OpenCode 中查看 Start 教程,熟悉基本操作:

  • 如何创建新项目
  • 如何使用自然语言编写代码
  • 如何预览和测试代码

步骤 3:创建个人网站项目(30 分钟)

打开 OpenCode,使用自然语言描述需求:

请帮我创建一个简洁的个人网站,包含以下内容:
- 首页:自我介绍、联系方式、作品展示
- 设计风格:简洁现代,响应式设计
- 技术栈:HTML + CSS + JavaScript
- 包含导航栏和页脚

OpenCode 会自动生成代码,你可以:

  1. 审查生成的代码
  2. 提出修改意见
  3. 要求添加更多功能

步骤 4:创建 GitHub Pages 仓库(10 分钟)

  1. 登录 GitHub
  2. 点击右上角的 "+" 按钮
  3. 选择 "New repository"
  4. 仓库名称格式:你的用户名.github.io
    • 例如:zhangsan.github.io
  5. 设置为 Public(公开)
  6. 点击 "Create repository"

重要: 仓库名称必须是 用户名.github.io 格式!

步骤 5:创建网站文件(15 分钟)

在 OpenCode 中,根据之前生成的代码,创建以下文件结构:

你的项目文件夹/
├── index.html # 首页
├── css/
│ └── style.css # 样式文件
├── js/
│ └── main.js # JavaScript 文件
└── img/ # 图片资源

在 OpenCode 中生成每个文件的内容。

步骤 6:推送代码到 GitHub(15 分钟)

6.1 初始化 Git

在你的本地项目文件夹中,打开命令行:

# 初始化 Git 仓库
git init

# 添加所有文件
git add .

# 提交代码
git commit -m "初次部署个人网站"

6.2 关联 GitHub 仓库

# 添加远程仓库地址(替换成你的用户名)
git remote add origin https://github.com/你的用户名/你的用户名.github.io.git

# 推送代码到 GitHub
git push -u origin main

如果遇到错误,尝试使用:

git branch -M main
git push -u origin main

步骤 7:等待部署(10 分钟)

GitHub Pages 会自动检测到 用户名.github.io 仓库,并开始部署。

  1. 访问 https://你的用户名.github.io
  2. 等待 1-2 分钟
  3. 刷新页面,你的网站就上线了!

查看部署状态:

  • 进入仓库 → Settings → Pages
  • 查看部署状态和历史

步骤 8:更新和迭代(随时)

网站部署后,你可以随时更新:

  1. 在 OpenCode 中修改内容
  2. 提交更改:git add . && git commit -m "更新内容"
  3. 推送到 GitHub:git push
  4. 等待自动部署完成

检查点

✔ 成功注册 GitHub 账户 ✔ 下载并配置了 OpenCode ✔ 添加了 glm-4.7 模型 ✔ 熟悉了 Start 教程 ✔ 创建了个人网站项目 ✔ 创建了 GitHub Pages 仓库 ✔ 成功推送代码到 GitHub ✔ 访问你的网站正常显示

踩坑提醒

问题 1:仓库名称错误

问题: 网站无法访问,显示 404 错误

原因: 仓库名称不是 用户名.github.io 格式

解决: 检查仓库名称,确保格式正确

问题 2:推送代码失败

问题: 执行 git push 时报错

原因: 网络问题或权限问题

解决:

  • 检查网络连接
  • 确认 GitHub 账户和权限
  • 尝试使用 SSH 而不是 HTTPS

问题 3:网站部署慢

问题: 推送代码后网站很久才更新

原因: GitHub Pages 部署需要时间

解决: 耐心等待 1-2 分钟,或查看 Pages 设置中的部署状态

问题 4:OpenCode 生成的代码有问题

问题: 生成的代码不能正常运行

原因: 需求描述不够详细

解决: 更详细地描述需求,提供更多上下文信息

本课小结

恭喜你!🎉

你现在拥有了:

  • 一个完全免费的个人网站
  • 掌握了 GitHub Pages 部署技能
  • 学会了使用 OpenCode + glm-4.7 编程
  • 可以随时更新和改进你的网站

下一课预告

下一篇文章将介绍如何使用 OpenCode 实现更多高级功能,比如添加博客系统、评论功能等,敬请期待!

Docusaurus 静态网站最佳实践

· 阅读需 2 分钟

Docusaurus 是一个优秀的静态网站生成器,本文分享一些最佳实践。

一句话总结

用好 Docusaurus,让静态网站更快速、更专业。

核心笔记

  • 合理组织文档结构
  • 使用 MDX 增强文档功能
  • 优化搜索和 SEO
  • 利用主题定制打造独特风格

学完你能做什么

完成本教程后,你将能够:

  • 快速搭建专业的文档站
  • 优化网站性能和 SEO
  • 自定义主题和样式
  • 集成常用功能

你现在的困境

  • 不知道如何组织文档结构
  • 不熟悉 Docusaurus 的高级功能
  • 网站加载速度慢
  • 搜索功能不好用

什么时候用这一招

  • 搭建技术文档站时
  • 创建项目主页时
  • 需要快速迭代内容时

核心思路

Docusaurus 提供了丰富的配置和插件,合理使用这些功能可以大大提升网站质量。

跟我做

实践 1:优化文档结构

docs/
├── getting-started/
│ ├── installation.md
│ ├── configuration.md
│ └── quick-start.md
├── guides/
│ ├── basic-usage.md
│ └── advanced-features.md
└── api/
└── reference.md

实践 2:使用 MDX 示例

Docusaurus 支持 MDX,可以在 Markdown 中使用 React 组件。比如 Tabs 组件:

console.log('JavaScript');
console.log('TypeScript');

实践 3:优化 SEO

docusaurus.config.ts 中添加元数据优化 SEO:

themeConfig: {
metadata: [
{
name: 'description',
content: '你的网站描述',
},
],
},

实践 4:自定义主题

// swizzle Footer 组件
npm run swizzle @docusaurus/theme-classic Footer

检查点

✔ 文档结构清晰合理 ✔ 熟悉 MDX 基本语法 ✔ 掌握 SEO 优化技巧 ✔ 能自定义主题组件

踩坑提醒

问题: 页面加载慢 原因: 图片未优化 解决: 使用 next/image 或优化图片格式

问题: 搜索功能不好用 原因: 没有配置 algolia 解决: 集成 Algolia DocSearch

本课小结

Docusaurus 功能强大,合理使用可以事半功倍。