本地开发
启动应用、执行检查与维护数据库查询。
环境
应用仓库需要 Go 1.26+、Node.js 24 与 packageManager 指定的 pnpm 9.12.2。安装脚本的合成发布测试需要 jq。Docker 仅用于容器验证，不是本地开发的前提。
以下命令在 SubLane 应用仓库根目录 执行，不是在独立官网的 website/ 目录。
make setup
make dev常用命令
| 命令 | 用途 |
|---|---|
make dev | 同时启动 Air 后端自动重载与 Vite 前端 HMR |
make dev-api、make dev-web | 分别启动带 Air 自动重载的后端与 Vite |
make build | 构建前端并嵌入 bin/sublane |
make generate | 根据 SQL 重新生成 sqlc 查询代码 |
make generate-check | 检查生成结果漂移 |
make test | 脚本、Go race 与前端测试 |
make lint | 格式、vet、类型与 lint |
make check | 所有检查及生产构建 |
make clean | 清理构建输出，不删除数据库与依赖 |
修改 Go 源码、内嵌 SQL、go.mod 或 go.sum 后，Air 自动重新编译并重启后端。前端由 Vite 提供 HMR，不触发后端重启。前端端口占用时使用 make dev WEB_PORT=5174。
Makefile 通过 go run 使用固定版本 Air v1.67.4，首次运行会下载并编译，无需全局安装，也不会把 Air 依赖加入应用模块。.air.toml 将临时构建放在已忽略的 bin/air/ 下，重启前为后端保留最多十秒的正常关闭时间。开发后端与生产构建一样关闭 CGO，避免 macOS C 链接器的最低系统版本不一致警告；race 测试继续使用 CGO。
环境变量
复制 .env.example 不会自动启用变量，需要 shell 导出或命令前缀：
SUBLANE_LOG_LEVEL=debug make dev
SUBLANE_ADDR=127.0.0.1:9090 ./bin/sublaneWEB_PORT 只修改前端端口。后端默认监听 127.0.0.1:8080，Vite 自动读取与后端相同的 SUBLANE_ADDR。如果已有 Docker 实例或其他进程占用 8080，可使用独立后端端口：
SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174make dev 会在启动 Air 与 Vite 前检查后端地址，地址已被占用时直接报错，避免后端监听失败但 Air 仍运行时，新前端误连到其他或旧版服务。分别运行 make dev-api 和 make dev-web 时，两条命令需传入相同的 SUBLANE_ADDR。
代理保留 Host（changeOrigin: false）以满足同源认证。开发初始化使用空的临时数据目录与合成账号，不能删除工作实例数据库来重置环境。
测试要求
go test ./internal/server -run TestRoutesAndAssetBoundary -count=1
pnpm --dir web test src/App.test.tsx只用合成凭据、模拟上游和临时数据库。行为改动先补失败测试，再实现并运行相关检查。浏览器还需检查桌面与窄屏、直接路由刷新、语言切换、主题和后端断连状态。
保留 internal/storage/migrations/ 中的现有迁移，包括 001_schema.sql；后续结构变更新增按顺序执行的增量迁移，并更新 internal/storage/queries/ 中的命名查询。启动时会为受支持的数据库执行缺失迁移；包含 001_settings.sql 的早期不兼容结构会被拒绝。运行 make generate、make generate-check 和相关存储测试；sqlc 验证结构，不负责迁移运行中的数据库。真实服务商验收使用独立授权的测试账号，不能采用生产数据作为测试样本。
官网开发
官网在相邻的 website/ 目录维护，使用 Next.js 与 Fumadocs。英文内容位于 content/docs/，其他语言位于 content/<locale>/，同名文件对应同一主题。界面、官网和文档均支持 11 种语言；新增翻译由机器辅助生成，需要母语使用者进一步校对。命令、代码、链接和插值变量必须保持不变。官网使用自身的 package.json，独立执行 pnpm dev --port 3100、pnpm test、pnpm test:e2e 和 pnpm build。