2. 开发环境与工作流

架构选型确定后，搭建高效的开发环境。本章覆盖从"AI 辅助设计"到"编码工作流"再到"网络原理"的完整链路。

2.1 整体工作流概览

需求想法 → [Gemini] 需求具象化 → [Stitch] 视觉设计 → [Cursor] 编码实现
                                                                     ↓
                                                    [Docker Desktop] 本地验证
                                                                     ↓
                                                    [Git] 提交 → [GitHub] 远程存储
                                                                     ↓
                                                    [SSH] 服务器拉取 → 部署上线

2.2 视觉设计工作流（Vibe Coding + Google Stitch）

为什么需要"先设计再编码"？

普通开发者甚至资深工程师，往往缺乏专业的 UI 审美储备。直接在 Cursor 中用文字描述 UI 效果，受限于自己的辞藻。而 Stitch 的视觉审美上限远高于人类的语言描述上限。

四步工作流

第一步：需求具象化（Gemini 深度沟通）

操作：将模糊的需求描述抛给 Gemini
示例：将"我想要一个高级感的课程页"转化为"一个使用奶油白背景、深绿色强调色、带有侧边栏分类和响应式网格的现代教育 UI 提示词"
原理：Gemini 扮演需求分析师，将人类语言翻译为设计模型能理解的 Prompt

第二步：视觉资产生成（Google Stitch）

操作：将 Gemini 优化后的 Prompt 输入 Stitch，关联参考网址
产出：3 个不同变体的 UI 方案，附带生产级 HTML/Tailwind CSS 或 React 代码
原理：Stitch 扮演 UI 设计师，从海量设计数据库中提取最优视觉方案

第三步：视觉审计与迭代

操作：将 Stitch 生成结果截图回传给 Gemini，进行审美判断
迭代：针对不足处（"颜色太蓝"、"边距太挤"）让 Gemini 更新 Prompt
原理：形成闭环反馈系统，确保最终产出高度符合审美标准

第四步：逻辑落地（Cursor 代码集成）

操作：从 Stitch 下载代码 → 导入 Cursor 项目
后续：Cursor 负责组件化、状态管理、路由跳转等逻辑开发
原理：Cursor 扮演前端架构师，此时面对的不再是模糊描述，而是一份现成的代码骨架

核心原则

Stitch 负责"美"（布局、颜色、字体、间距），Cursor 负责"动"（数据流、交互状态、组件复用）。这种"视觉与逻辑解耦"避免了让代码模型做它不擅长的美工工作。

2.3 Windows 开发的特殊考量

核心矛盾：Windows 开发 vs Linux 部署

你的开发电脑是 Windows，但服务器是 Ubuntu (Linux)。解决方案是利用 Docker 抹平环境差异，利用 SSH 跨越物理距离。

本地开发到底在哪跑？

你的 Windows 电脑
    ↓
Docker Desktop (基于 WSL2)  →  启动一个轻量 Linux 内核
    ↓
docker-compose up           →  代码挂载到 Linux 容器内运行
    ↓
浏览器访问 localhost:3000   →  看到的效果 = 服务器上跑的效果

原理说明：

Docker Desktop 安装后，Windows 通过 WSL2 在后台运行一个极轻量的 Linux 内核

你执行 docker-compose up，代码被挂载到容器内的 Linux 环境运行

你在 Windows 浏览器访问 localhost:3000 就能看到效果

保证了本地看到的效果与服务器一致

电脑性能与服务器的关系

原理说明：

开发对电脑性能有一定要求（Docker 比较吃内存）

但操作服务器对电脑性能零要求

当你通过 SSH 连接服务器时，Windows 只是一个"远程窗口"

所有计算（数据库查询、AI 处理）消耗的是云服务器的资源

你的电脑就像电视遥控器，服务器是远在北京的高性能电视机

2.4 开发者标准闭环流水线

这是每日开发的"标准动作"：

1. 编码      →  在 Windows 使用 Cursor 敲代码
2. 本地验证  →  Docker Desktop 启动，访问 localhost 检查
3. 代码提交  →  git push 到 GitHub（代码进入云端仓库）
4. SSH 登录  →  ssh root@服务器IP 连接北京服务器
5. 拉取部署  →  git pull + docker-compose up -d --build

Git：不仅仅是传输工具

为什么部署必须经过 Git，而不是直接复制文件？

优势	说明
版本避险	Git 记录每次修改，服务器更新后挂了可秒级回滚
增量传输	改一个字母只传一个字母的数据，而非整个文件夹
自动化基石	未来可配置 CI/CD，`git push` 即自动部署

两种部署模式对比

模式	流程	优点	适合场景
代码级更新（推荐）	Git 传代码 → 服务器现场 `docker build`	流程简单，无需镜像仓库	个人项目、初期开发
镜像级更新（标准）	本地打包 → 推镜像库 → 服务器 `pull`	稳定，服务器无需编译环境	团队协作、生产环境

2.5 开发环境网络访问原理

理解网络原理，是排查"网页打不开"的必备技能。

"监听"是什么意思？

监听 = 程序在某个"门牌号"上等待请求。

门牌号：IP 地址 + 端口号（如 192.168.1.100:3000）
监听：程序在该地址上持续运行，有请求进来就处理

一台电脑有多个可用地址

网卡类型	示例 IP	谁能访问
回环接口	`127.0.0.1`（localhost）	只有本机
WiFi 网卡	`172.19.22.228`	本机 + 同一 WiFi 下设备
有线网卡	`192.168.1.100`	本机 + 同网段设备

为什么必须监听"所有网卡"？

监听方式	localhost	手机访问
`127.0.0.1:3000`（仅回环）	✅	❌
`0.0.0.0:3000`（所有网卡）	✅	✅

原理说明：

127.0.0.1 和 172.19.22.228 属于不同网卡

只监听 127.0.0.1 → localhost 可用，手机访问不到

只监听 172.19.22.228 → 手机可用，但 localhost 不可用

0.0.0.0 表示"在所有网卡上监听"，一次配置满足两种场景

关于 0.0.0.0 的重要说明

# ✅ 监听用 0.0.0.0（告诉程序在所有网卡上工作）
npm run dev -- --hostname 0.0.0.0

# ❌ 访问千万不要用 0.0.0.0
# http://0.0.0.0:3000 → 返回 502 Bad Gateway
# 请使用实际的局域网 IP，如 http://172.19.22.228:3000

原理说明：

0.0.0.0 是服务端绑定地址，表示"监听所有网卡"——不是一个可访问的地址

在浏览器输入 http://0.0.0.0:3000 会报 HTTP 502

Next.js 收到 --hostname 0.0.0.0 时，Network 输出显示 http://0.0.0.0:3000，但这是 Next.js 的显示逻辑，切勿用该地址访问

自定义 dev 脚本的实现原理

项目中的 npm run dev 并非直接运行 next dev，而是通过自定义脚本添加了手机访问功能：

// frontend/scripts/dev.mjs 核心逻辑
function getLocalIP() {
  const interfaces = os.networkInterfaces();
  // 遍历网卡，筛选 IPv4、非回环、非 198.18 的地址
  // 优先 192.168/10/172.16-31 等常见局域网网段
  return preferred ?? fallback;
}

if (ip) console.log("\n📱 手机访问（同一 WiFi 下）: http://" + ip + ":3000\n");

spawn("npx", ["next", "dev", "--hostname", "0.0.0.0"], {
  stdio: "inherit",
  shell: true,   // Windows 下正确解析 npx
});

原理说明：

脚本先通过 Node.js 的 os.networkInterfaces() 获取本机局域网 IP

打印手机访问地址，然后才启动 next dev

--hostname 0.0.0.0 让 Next.js 监听所有网卡（手机才能访问）

副作用：Next.js 的 Network 会显示 0.0.0.0，因此脚本需要单独打印可用 IP

手机访问速查

1. 手机和电脑连接同一 WiFi
2. 电脑运行 npm run dev
3. 查看终端输出：📱 手机访问: http://x.x.x.x:3000
4. 手机浏览器输入该地址即可访问

2.6 关键工具小结

工具	作用
WSL2	让 Windows 拥有原生 Linux 能力的底层引擎
Docker Desktop	在 Windows 上管理容器的可视化工具
Git	代码的版本管理器与传输通道
SSH	连接 Windows 与 Linux 服务器的加密安全通道

← 返回知识库 | → 下一篇：安全架构