企业官网建设流程全解析

这次我们来看一个具体案例：用 Claude Code 搭建一套农业物联网监测平台。Claude Code 是 Anthropic 推出的命令行 AI 编程工具，它不只是帮你补全代码，而是可以直接在终端里理解需求、读写项目文件、执行命令、跑测试，相当于一个能动手改代码的 AI 开发助手。农业物联网这个案例有意思的地方在于，它不是一个简单的 CRUD 练习，而是把设备接入、数据采集、实时展示、异常告警串成一条完整链路，正好能检验 AI 编程 Agent 能不能从零把一个系统搭起来。

本文会围绕“Claude Code 100 个案例”这个主线，以农业物联网监测平台作为实操目标，给出从环境准备、安装启动、分阶段编码、效果验证到接口调用和自动化批量任务的完整流程。我不会只讲概念，重点是你照着操作能否跑通，以及遇到问题怎么排查。如果你正在关注 Claude Code 怎么落地真实项目，或者准备做 IoT 方向的小型平台，这篇文章可以直接收藏。

1. Claude Code 核心能力速览

先把 Claude Code 本身的能力和本次农业物联网案例的定位放在一张表里，方便快速判断这个工具适不适合你。

从工具角度看，Claude Code 会把“需求 + 项目规则 + 当前文件状态”统一放进上下文，然后通过工具调用完成文件修改和执行命令。这套机制决定了它适合做多文件工程，而不只是单文件的代码生成。农业物联网监测平台恰好是多模块项目，适合拿出来当一个完整的 Agent 工作流示范。

2. 农业物联网监测平台要解决什么问题

农业物联网监测平台的核心需求可以拆成四块：传感器数据采集、数据存储与管理、实时可视化监控、异常阈值告警。典型的场景是温室大棚里部署温度、湿度、土壤水分、光照等传感器，数据通过 MQTT 或 HTTP 上报到平台，平台把这些数据存下来，在 Web 页面上展示实时曲线，遇到温度过高、土壤过干等异常时触发告警。

用 Claude Code 来搭这套系统，重点不是让 AI 一次性吐出所有代码，而是把它当成一个能持续沟通的工程助理。你可以先让它搭骨架，再逐步补充数据模型、采集接口、前端页面和告警规则，每一步都能运行验证后再进入下一步。这样做的好处是，AI 生成的内容始终处于可运行状态，而不是一个看起来很完整却跑不起来的代码堆。

这个案例适合谁？适合想了解 AI 编程 Agent 如何参与真实项目开发的开发者，适合需要快速搭建 IoT 原型在做毕设或内部展示的学生和工程师，也适合想验证 Claude Code 是否能替代部分重复编码工作的人。不适合的场景是：直接把 AI 生成的代码部署到生产温室控制系统中不做审查，这风险太高；另外，如果涉及真实农场的地理位置、产量、经营数据，必须先处理数据合规和访问权限，不能为了演示随意采集真实数据。

在合规和隐私方面要特别强调：本文所有内容都围绕本地开发测试展开，不要用公网开放访问你的农业平台。涉及设备控制、自动化灌溉、卷帘电机等执行操作时，必须做人工授权和操作审计，不能让 AI 生成的接口直接控制实体设备。

3. Claude Code 环境准备与前置条件

在开始搭建农业物联网平台之前，先把 Claude Code 的运行环境准备好。整个链条并不复杂，但 Node 版本不对会直接导致安装失败。

第一，操作系统。Windows、macOS、Linux 都可以跑 Claude Code，下面命令在 Windows 上建议通过 PowerShell 或 Git Bash 执行，macOS/Linux 直接在终端执行。本文以类 Unix 环境为主，Windows 用户只需要把命令中的路径和环境变量写法按系统习惯调整一下。

第二，Node.js 版本。Claude Code 是 npm 包，要求 Node.js 18 及以上。先检查当前版本：

node -v npm -v

如果版本过低，建议用 nvm 安装较新的 Node LTS 版本，不要把系统自带的 Node 环境弄乱。这一步如果没做对，后面安装 Claude Code 会出现各种模块加载错误，排查起来很浪费时间。

第三，IDE 或终端。你可以直接在系统终端里用 Claude Code，也可以在 VS Code 的终端里使用。如果你习惯图形界面，在 VS Code 中打开项目目录，然后调出终端运行claude即可。VS Code 的好处是能实时看到 AI 修改文件的 diff，方便 review。

第四，认证准备。Claude Code 启动后通常需要登录 Anthropic 账号，或者通过ANTHROPIC_API_KEY环境变量配置 API Key。团队或组织账号如果禁用了 Claude 订阅访问 Claude Code，需要联系管理员确认权限，或改用 API Key 方式。

# 设置 API Key，实际 Key 需要替换为你自己的 export ANTHROPIC_API_KEY="sk-你的key"

如果你使用的是兼容接口或第三方模型网关，需要把ANTHROPIC_BASE_URL等环境变量一并配置好，并确认模型名和接口格式与当前 Claude Code 版本兼容。

4. Claude Code 安装与启动方式

Claude Code 的安装很简单，npm 全局安装一条命令：

npm install -g @anthropic-ai/claude-code

安装完成后确认版本：

claude --version

如果以后需要更新，执行：

claude update

启动方式分两种。第一种是交互模式，进入项目目录后直接运行claude，然后在终端里用自然语言描述需求。第二种是单次任务模式，直接传入提示词，适合脚本化调用：

# 交互模式 cd farm-iot claude # 单次任务模式，生成 README claude "为当前项目生成一个 README.md，包含项目简介和启动方式"

在交互模式里，有一些常用操作需要记住：/init可以初始化项目上下文，/add-dir可以把目录加入上下文，/compact可以压缩过长的上下文，/clear清空当前对话，/status查看当前状态。如果上下文太长导致生成质量变差，优先用/compact，不要盲目新开对话。

启动后，Claude Code 会在项目目录下自动管理工作文件。为了让它更好地理解你的需求，我建议在项目根目录创建CLAUDE.md，把技术栈和约束写进去。下面是一份农业物联网项目的规则示例：

# CLAUDE.md ## 项目目标 构建一个农业物联网监测平台，覆盖传感器数据采集、存储、可视化与告警。 ## 技术栈 - 后端：Python FastAPI - 数据库：SQLite（开发）/ PostgreSQL（生产） - 前端：Vue 3 + Vite + ECharts - 传输协议：MQTT（备选 HTTP API） - 认证：开发阶段可跳过，生产必须接入登录鉴权 ## 项目约束 - 生成的代码必须提供启动方式说明 - 敏感配置统一放 .env，不要写入代码 - 设备控制类接口必须添加权限校验

CLAUDE.md的作用是让 AI 在每次生成代码时都遵守这些约定。没有这个文件，Claude Code 只能靠当前对话的上下文，一旦会话变长就容易偏离方向。

5. 用 Claude Code 搭建农业物联网平台：分阶段实操

这一部分是重点。我会把整个搭建过程拆成四个阶段，每个阶段都给出提示词示例、预期产物和验证方式。建议你按阶段执行，不要一次性让 Claude Code 生成全部代码，否则后面排错会非常痛苦。

5.1 阶段一：初始化项目骨架

第一个阶段的目标是跑通一个最小可运行的前后端骨架。不要一上来就加入传感器、数据库、MQTT 等复杂功能。

在空目录farm-iot下启动 Claude Code 后，输入：

我们在当前目录搭建农业物联网监测平台。请先初始化项目骨架： 1. 后端使用 Python FastAPI，提供 /health 健康检查接口 2. 前端使用 Vue 3 + Vite，首页显示系统状态卡片 3. 开发阶段先不用数据库，页面数据用 mock 4. 生成启动说明 README.md 5. 完成后再告诉我如何启动和验证

预期产出是一个包含backend和frontend子目录的项目骨架。这里要重点验证两件事：后端能否启动并返回健康检查信息，前端能否启动并显示页面。不要继续往后做功能，先把两个服务跑通。

如果 Claude Code 在生成过程中使用了虚拟环境或 npm 安装依赖，注意看终端输出是否成功。这一步常见的坑是 Python 版本和 Node 版本不匹配，后续我在第九章统一说明排查方法。

5.2 阶段二：传感器数据采集与设备管理

骨架跑通后，进入核心业务开发。这个阶段要完成三件事：设备管理的数据模型、模拟传感器数据上报、Rest API 接口。

继续在 Claude Code 交互中提示：

在现有骨架上增加物联网数据模块： 1. 定义 Device 模型，字段包括 id、name、location、sensor_types、status 2. 定义 SensorRecord 模型，字段包括 device_id、sensor_type、value、unit、created_at 3. 开发阶段使用 SQLite 存储，用 SQLAlchemy 管理 4. 提供设备注册、设备列表、传感器数据写入、传感器数据查询接口 5. 写一个 simulator/sensor_sim.py，模拟温湿度数据定时上报 6. 完成后给出接口文档和启动步骤

如果这一阶段生成顺利，你会看到一个具备基础 CRUD 能力的后端，同时有一个模拟传感器数据的脚本。这里建议让 Claude Code 顺便生成一个docs/api.md，把接口的作用、参数和返回示例记录下来。这个文档后面无论是自测还是接入前端，都非常有用。

验证方式：先启动后端，然后单独运行传感器模拟脚本，最后通过接口查询数据。例如：

# 查询设备列表 curl http://127.0.0.1:8000/api/devices # 查询某个设备最近的温湿度数据 curl http://127.0.0.1:8000/api/devices/1/records?limit=20

这个阶段最值得检查的是数据模型设计是否合理：传感器类型是否可扩展，时间字段是否带时区，设备状态是否便于后续做在线离线判断。如果发现 AI 生成的数据模型有缺陷，直接让它修改，不用自己动手。

5.3 阶段三：实时监测与可视化

数据已经能写入，接下来把它展示出来。这个阶段引入 WebSocket 和 ECharts。

在现有基础上增加实时监测页面： 1. 后端增加 WebSocket 接口，用于向前端推送最新传感器数据 2. 传感器模拟脚本改为持续上报，并支持多个设备 3. 前端增加实时曲线页面，用 ECharts 展示温度和湿度变化 4. 如果没有新数据，页面不要闪烁，保持稳定 5. 完成后说明如何同时启动后端、模拟器和前端进行联调

这里建议让 Claude Code 把模拟器改成可以指定设备数量和上报频率，方便后续测试实时性。当前端实时曲线能随模拟数据滚动时，这个阶段就算通过。

联调过程中要注意：WebSocket 的地址不能写死，端口和路径要和后端配置一致。如果页面里没数据，优先查看浏览器开发者工具里的网络请求和 WebSocket 连接状态，再回过头看后端日志。

5.4 阶段四：告警规则与阈值触发

最后一个核心功能是告警。农业物联网平台的告警逻辑通常不复杂，但对工程化要求比较高。

增加告警模块： 1. 支持为设备配置告警规则，例如当 temperature 大于 35 或 soil_moisture 小于 30 时触发 2. 后端在写入传感器数据时判断规则，触发后生成 AlertRecord 3. 提供告警记录查询接口，支持按设备、规则、时间范围筛选 4. 模拟器里故意产生一条温度越界数据，验证告警能触发 5. 前端告警页面展示最新告警列表和状态

这一阶段判断成功的关键是端到端能跑通：设备注册、模拟数据写入、规则匹配、告警生成、前端展示。除了正常流程，还要检查异常流程，比如阈值配置错误时接口是否会返回明确报错，避免埋雷。

告警模块做完后，这个农业物联网监测平台的 MVP 就成立了。如果你还想继续扩展，可以让 Claude Code 增加历史数据统计、批量导出 CSV、日报生成等能力，这些放在批量任务章节讲。

6. 功能测试与效果验证

AI 生成的代码如果不做系统性验证，很容易出现“看起来对，跑起来错”的情况。建议按照下面的测试维度逐项验证。

第一，基础生成能力测试。分别测试设备注册、数据写入、数据查询三个核心接口，确认接口能通，返回字段符合预期。

第二，实时推送测试。启动多个模拟传感器后，确认 WebSocket 能持续推送数据，前端不再依赖手动刷新。

第三，告警触发测试。将某个设备的温度阈值调到很低，比如 10 度，然后让模拟器上报 30 度，确认告警记录能被创建并展示。

第四，批量数据测试。用脚本一次性写入 1000 条传感器数据，观察接口响应时间和页面加载是否正常。这个测试不需要很高的并发量，重点是确认数据库设计和查询语句没有明显性能问题。

第五，异常输入测试。提交不存在的设备 ID、空数据、超大数值，确认接口能返回清晰的错误信息而不是直接 500。

如果你不想手工点接口，可以让 Claude Code 生成一套 pytest 测试用例。提示词可以这样写：

为当前后端项目生成 pytest 测试： 1. 测试设备注册、列表、详情接口 2. 测试传感器数据写入和查询 3. 测试告警规则触发逻辑 4. 测试非法输入返回 422 或 400 5. 测试结束后给出运行命令

有了自动化测试，后续再让 Claude Code 改代码时，回归成本会低很多。

7. 接口 API 与批量任务自动化

农业物联网监测平台做出来后，下一步通常是接入更多设备或做定时统计任务。这部分工作可以用 Claude Code 快速扩展。

先看一个手动调用接口的示例。假设后端地址是http://127.0.0.1:8000，注册设备并写入数据：

curl -X POST http://127.0.0.1:8000/api/devices \ -H "Content-Type: application/json" \ -d '{"name":"温室1号","location":"A区-1号棚","sensor_types":["temperature","humidity","soil_moisture"]}'

如果你更喜欢用 Python 脚本批量注册设备，参考下面的请求模板：

import requests BASE = "http://127.0.0.1:8000" def register_device(name: str, location: str, sensor_types: list): resp = requests.post( f"{BASE}/api/devices", json={"name": name, "location": location, "sensor_types": sensor_types}, timeout=10, ) print(resp.status_code, resp.json()) # 批量注册示例 for i in range(1, 6): register_device(f"温室{i}号", f"A区-{i}号棚", ["temperature", "humidity"])

在实际生产中，批量任务要考虑失败重试和幂等性。设备注册如果重复提交，会创建重复记录，所以项目里要加唯一标识或去重逻辑。这一点可以在设计阶段直接要求 Claude Code 实现。

再看 Claude Code 自身怎么承担批量自动化任务。它支持非交互模式，可以把任务交给脚本或 CI：

# 让 Claude Code 读取需求文件并生成代码 claude -p "读取 docs/tasks.md 中的任务列表，逐项实现，并运行测试确认通过" --output-format json

比如你有一个 agriculture 的定时日报需求：每天统计各设备的平均温度、平均湿度、异常次数，然后生成 Markdown 报告。你可以让 Claude Code 生成一个定时脚本，再通过 cron 或任务计划程序每天调用。这样平台就从“能看数据”升级为“能自动产出决策信息”。

使用非交互模式时，建议把任务描述写清楚，明确输入和输出文件路径，避免 AI 在“哪个目录、生成什么格式”上猜测。如果任务太大，拆成多个子任务依次执行，稳定性会好很多。

8. 资源占用与性能观察

性能方面没有一个适用于所有机器的固定数字，要结合你的实际环境和配置来观察。农业物联网平台运行时的资源占用主要来自四个环节：传感器数据写入、数据库查询、WebSocket 实时推送、前端图表渲染。

先看后端。FastAPI 在本地开发时资源占用通常不高，但如果数据写入频率很高，SQLite 会成为瓶颈。SQLite 适合单机开发和低并发场景，如果传感器数量达到几十上百个，并且上报间隔很短，建议切换到 PostgreSQL，这一步可以在项目初期就写进 CLAUDE.md。

再看前端。ECharts 实时曲线在数据点很多时会比较消耗 CPU，解决思路是前端只保留最近 N 条数据，或者后端做聚合。你可以让 Claude Code 生成一个数据聚合接口，按分钟或小时粒度返回统计值，大幅降低前端渲染压力。

观察资源占用的方式很简单，本地运行后端和前端后，使用系统自带的资源监视器或top命令查看 CPU 和内存。关于 Claude Code 本身，值得注意的是上下文消耗。AI Agent 的 token 消耗会随会话长度增长，长时间会话后如果发现响应变慢，优先使用/compact压缩上下文，再继续任务。

如果需要压测，可以让 Claude Code 生成一个简单的压力测试脚本，模拟 100 个设备、每个设备 10 秒上报一次数据。但不要因为是 AI 生成的脚本就让它在生产环境直接跑，先在本机验证，观察数据库和接口的承受能力。

9. Claude Code 与项目常见问题排查

这一章列出实际操作中最容易遇到的问题，按“现象、原因、排查、解决”的结构整理成表。

列在这里的排查方案是通用处理思路，具体到你的环境，还是要以实际报错内容为准。遇到问题先看日志，不要上来就删文件重装，那样往往更浪费时间。

10. 最佳实践与使用建议

基于农业物联网平台这个案例，我总结了 7 条 Claude Code 工程化使用的建议。

第一，把 CLAUDE.md 当作项目契约。技术栈、目录结构、读写规范、禁止事项都写进去。AI Agent 的上下文是有限的，项目规则写清楚，它能减少很多无效尝试。

第二，每个阶段先跑通再进入下一步。骨架、数据模块、可视化、告警，四个阶段拆分执行，每步都有验证动作。这样排错范围小，也方便用 git 回退到可用状态。

第三，让 AI 生成测试。不仅是业务代码，测试代码也交给 Claude Code 写。有了测试，后面做代码修改时，AI 可以自己跑测试并修复回归问题。

第四，不要让 AI 直接执行破坏性命令。例如清空数据库、删除目录、覆盖生产配置这类操作，要在提示词里明确禁止。开发环境内可以试验，但也要先确认分支可回滚。

第五，敏感配置不进仓库。数据库连接串、API Key、设备密钥统一通过.env管理，并在.gitignore中忽略。尤其农业物联网平台可能连接到真实的设备网关，密钥泄露后果比普通 Demo 更严重。

第六，涉及设备控制必须加鉴权。如果平台将来要接自动灌溉、风机、卷帘等执行器，后端接口必须做用户认证和操作权限控制，并且保留操作日志。这块可以在 CLAUDE.md 里写死，强制 AI 生成代码时遵守。

第七，每完成一个功能就提交一次 git。这样做的好处是，AI 改坏代码之后可以快速回滚，也让 Claude Code 在判断当前项目状态时有更清晰的边界。

11. 总结与下一步

这个案例里最值得尝试的点，是用自然语言把一个农业物联网监测平台从零到一地搭出来。你可以亲眼看到 Claude Code 如何从项目骨架开始，逐步完成数据模型、接口、实时推送、告警和前端可视化，整个过程不是一次性生成大量代码，而是分阶段产出可运行的模块。

建议你先验证最小链路：安装 Claude Code，初始化一个 FastAPI 和 Vue 的骨架，自己跑通健康检查接口。这一步过了，再进入传感器数据模拟和实时曲线展示。最容易踩的坑集中在两个地方，第一是认证和账号权限问题，CLI 工具本身安装不难，难的是启动时的权限配置；第二是 AI 生成的代码依赖容易不完整，运行时报错要找对应模块补齐。

从扩展角度看，这个平台还可以继续加历史趋势预测、多温区管理、移动端小程序、设备在线离线监测、批量导出日报等能力。你甚至可以把“从 0 到 1 搭农业物联网平台”的方法复制到其他场景，比如环境监测、养殖场监控、仓库温湿度管理。本质上，Claude Code 省掉的是大量重复的 CRUD 和前后端胶水代码，但架构设计、权限控制和数据合规这些事情，仍然需要你自己把关。