# 04｜第一次把项目跑起来

前一站：[Web 基础](03-web-basics.md) · 下一站：[双账号体验](05-business-walkthrough.md)

## 本章的小目标

打开真实 Go 后端提供的页面，看到教学笔记，登录一个普通账号，并确认服务健康。所有命令都在项目根目录运行，不在 docs 中运行。

## 第一步：确认工具和位置

```powershell
Set-Location -LiteralPath 'D:\xiaolanshu-go'
go version
node --version
npm.cmd --version
```

Node 推荐 24.22.3，已有的 24.11.1 满足构建最低条件，但学习与复现优先使用项目固定补丁版本。项目带本地环境准备器：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1
```

它从 Node 官方服务器下载固定版本的 node.exe 到 `.tools/node`，核对 SHA256，不改变系统 PATH。npm 仍使用已有的 11.x。Go 版本由 go.mod 的 toolchain 声明控制。网络失败时先按[排错手册](../04-testing/troubleshooting.md)检查，不要关闭依赖校验。

## 第二步：构建并启动

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\dev.ps1
```

第一次会运行 npm ci、TypeScript 检查、Vite 构建和 Go 编译。看到下载日志是正常的。成功后输出 JSON 日志，包含“小蓝书 Go 已启动”和 `127.0.0.1:8080`。保持终端开启，在浏览器输入 `http://127.0.0.1:8080`。

若默认端口被占用，脚本应失败，不会杀死占用者。你可以新开终端执行 `$env:HTTP_ADDR='127.0.0.1:8086'` 再启动，并改为访问 8086。不是把浏览器地址改了，后端就会自动换端口。

## 第三步：获取验证码并登录

点右上角登录，填写 `13800000001`，点击获取验证码。本地开发环境生成随机六位码，页面自动填入，终端也显示这次验证码。点“登录 / 注册”，应看到昵称“蓝小满”。手机号没有记录时会自动创建新用户。

教学验证码机制只在 `APP_ENV=development` 返回 debugCode。它不是固定的万能码。不要自己随便填写 123456，也不要以为界面说已发送就意味着运营商真的发了短信。生产通过独立 HTTPS 短信适配器发送，不回传验证码。

## 第四步：确认后端确实工作

另开 PowerShell：

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8080/health/ready'
```

预期 `success=True`，data 内 status 为 ok，storage 为 SQLite WAL。浏览器开发者工具 Network 中应看到 `/api/search/note`，而不是全部操作都没有网络请求。若你曾开启 `VITE_DEMO_MODE=true`，改回 false 后重建。

## 第五步：认识生成的文件

| 路径 | 内容 | 是否可以随便删除 |
| --- | --- | --- |
| `bin/xiaolanshu.exe` | 后端构建产物 | 停止服务后可重新构建 |
| `frontend/dist` | 浏览器构建产物 | 可重新构建 |
| `data/xiaolanshu.db` | 用户、笔记、关系和会话 | 不要当缓存删除 |
| `data/.jwt-secret` | 开发环境持久密钥 | 删除会让已有会话失效 |
| `uploads` | 用户实际上传文件 | 与数据库一起备份 |
| `frontend/node_modules` | npm 安装依赖 | 可用 npm ci 重新安装 |

## 停止和第二次启动

回到服务终端按 Ctrl+C。程序等待当前请求结束，然后关闭数据库。再次运行 `scripts/dev.ps1 -SkipBuild` 可跳过构建；修改源码后需要重新构建。刷新页面仅重新读取当前状态，完整重启也不会自动清空数据。

验收：能看见笔记、登录、得到健康结果，知道数据库文件的位置。然后进入下一章，用两个身份验证业务规则。
