本地开发 | SubLane

环境

应用仓库需要 Go 1.26+、Node.js 24 与 packageManager 指定的 pnpm 9.12.2。安装脚本的合成发布测试需要 jq。Docker 仅用于容器验证，不是本地开发的前提。

以下命令在 SubLane 应用仓库根目录 执行，不是在独立官网的 website/ 目录。

安装依赖并启动应用开发环境

make setup
make dev

常用命令

命令	用途
`make dev-api`、`make dev-web`	分别启动后端与 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 后重启后端，Vite 支持前端 HMR。前端端口占用时使用 make dev WEB_PORT=5174。

环境变量

复制 .env.example 不会自动启用变量，需要 shell 导出或命令前缀：

覆盖开发运行参数

SUBLANE_LOG_LEVEL=debug make dev
SUBLANE_ADDR=127.0.0.1:9090 ./bin/sublane

Vite 默认代理后端 8080，改变后端端口时同步修改代理目标。代理保留 Host（changeOrigin: false）以满足同源认证。开发初始化使用空的临时数据目录与合成账号，不能删除工作实例数据库来重置环境。

测试要求

聚焦后端与前端测试

go test ./internal/server -run TestRoutesAndAssetBoundary -count=1
pnpm --dir web test src/App.test.tsx

只用合成凭据、模拟上游和临时数据库。行为改动先补失败测试，再实现并运行相关检查。浏览器还需检查桌面与窄屏、直接路由刷新、语言切换、主题和后端断连状态。

SQL 修改后执行 make generate 与 make generate-check；迁移必须保留持久化数据兼容，不能盲目增加连接数掩盖事务问题。真实供应商验收需要独立授权的测试账号，不能从生产数据构造测试样本。

官网开发

官网在相邻的 website/ 目录维护，使用 Next.js 与 Fumadocs。英文内容位于 content/docs/，中文位于 content/zh/，同名文件对应同一主题。官网使用自身的 package.json，独立执行 pnpm dev --port 3100、pnpm test、pnpm test:e2e 和 pnpm build。