# 本地配置、构建和开发环境

前置：[首次启动](../01-beginner/04-first-run.md) · 接着读：[生产与备份](production.md)

## 配置来源

Go读取**进程环境变量**，不自动解析.env。`scripts/dev.ps1` 逐字读取根.env并设置当前进程；直接 `go run ./cmd/server` 时需要你在当前终端设置变量。.env.example是说明模板，复制为.env后才能被启动器读取。值不执行PowerShell代码，不支持变量插值、行尾注释或额外引号语法，示例保持每行纯KEY=value。

| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| APP_ENV | development | 仅development/production |
| HTTP_ADDR | 127.0.0.1:8080 | 监听地址和端口 |
| DATABASE_PATH | data/xiaolanshu.db | SQLite持久路径 |
| UPLOAD_DIR | uploads | 上传文件目录 |
| FRONTEND_DIR | frontend/dist | 前端构建目录 |
| SEED_DEMO | true | 空库教学用户；production强制false |
| JWT_SECRET | 开发自动生成持久文件 | 生产必需>=32字节随机密钥 |
| ADMIN_USERNAME | admin | 首次初始化管理员名称 |
| ADMIN_PASSWORD | LanbookDev!2026 | 仅开发初始密码 |
| ADMIN_PASSWORD_HASH | 空 | 生产必需有效bcrypt；仅首次初始化使用 |
| SMS_WEBHOOK_URL | 空 | 生产必需HTTPS短信适配器 |
| SMS_WEBHOOK_TOKEN | 空 | 调适配器的私有Bearer凭证 |

相对路径基于启动工作目录。使用启动器会先切根目录；双击exe则工作目录可能不同，建议使用脚本或显式绝对路径。Windows目录可以含中文，file URI编码由database处理。

## 三种运行方式

完整运行：双击run-windows.cmd或执行dev.ps1，它安装锁定依赖、构建前端和Go，再前台运行exe；Ctrl+C停止。

只运行已构建版本：`powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\dev.ps1 -SkipBuild`。若改过Go源码或前端，需先build.ps1，否则仍看旧版本。

热更新：终端A运行Go，终端B `npm.cmd run dev --prefix frontend`，浏览器访问5173。Vite读取frontend/.env.local等环境文件；`VITE_BACKEND_TARGET`默认8080。VITE变量会编进浏览器，绝不能放JWT_SECRET、短信token或管理员密码。

## 独立演练数据

```powershell
$env:HTTP_ADDR='127.0.0.1:8086'
$env:DATABASE_PATH='data/lesson.db'
go run ./cmd/server
```

默认上传仍共用uploads。需要完全隔离时同时设置UPLOAD_DIR并记录路径。复制.env中同名变量会覆盖当前终端值，所以想临时设置时用go run或明确检查.env。新数据库为空才会种教学资料，已有普通用户时不会追加8篇演示记录。

## 产物与依赖

Go无需JVM，纯GoSQLite无需C编译器；exe仍需data/uploads可写与frontend/dist可读。Node只用于构建或热更新，正式运行Go静态站点不用Node进程。不要复制node_modules、Java target、IDE缓存或原项目密钥来“补环境”。

脚本使用项目.tools/node优先，版本固定且校验SHA256；工具下载不是系统级安装。npm依赖由package-lock固定。Windows中文.ps1保持UTF-8带BOM以兼容PowerShell5.1。

验收：分别运行普通模式和独立8086练习库，确认记录互不串用；再只运行exe证明Node不是后端运行时前提。
