开始开发

环境准备

使用 Node.js 24、根 packageManager 指定的 pnpm 12.15.0、JDK 21。 根 mise.toml 声明项目本地 Node 版本；使用 mise 时先运行 mise install。 后端当前依赖 wuli3 1.0.1-SNAPSHOT 构建插件与 Maven 制品，必须能够从 Maven Local 或已配置的仓库解析。 首次使用请按 Gradle 本机私服配置 安装私服和 SNAPSHOT 更新检查脚本。

在根目录运行：

pnpm install
pnpm dev:docs
pnpm dev:manage
pnpm dev:web

文档开发端口为 5609，pnpm docs:preview 的预览端口为 5619，后台为 5602，Vue 前台为 5604，后端为 5600。后端就绪后可用 pnpm dev 同时启动四个包。 端口由根启动命令传入，Turbo 透传环境；Vue 通过 CLI 指定端口，不修改 packages 内配置。

后端初始化

Swagger / OpenAPI

开发环境启动后访问 Swagger UI：http://localhost:5600/swagger-ui.html。 UI 可选择 client（客户端）或 admin（管理端）分组；点击 Authorize 输入登录返回的 JWT， 无需手动添加 Bearer 前缀，即可调试需要认证的接口。登录、注册接口无需授权。

OpenAPI 文档由控制器实时生成，不需要维护单独的 JSON 文件：

地址	内容
http://localhost:5600/v3/api-docs	全部业务接口 JSON
http://localhost:5600/v3/api-docs/client	/api/** 客户端接口
http://localhost:5600/v3/api-docs/admin	/admin-api/** 管理端接口

文档的成功响应包含 code、message、timestamp、requestId、data，与业务统一响应一致。 配置代码位于 packages/service/alang-bootstrap/src/main/java/com/kr/alang/config/OpenApiConfiguration.java， 接口摘要和安全声明位于各模块的 Controller。

开发环境默认开启，生产 profile 默认关闭。设置 OPENAPI_ENABLED=false 后重启可关闭 JSON 和 UI； 需要在生产环境查看时显式设置 OPENAPI_ENABLED=true。通过根 Turbo 启动时也会透传此变量。

基础服务与数据库

准备 MySQL 和 Redis，以及需要联调的 RocketMQ 等服务。创建 alang 数据库， 执行 packages/service/alang-user/alang-user-service/src/main/resources/sql/user-auth.sql。 其余 SQL 脚本按对应模块说明执行，不假设存在自动迁移机制。

在启动终端配置 DB_HOST、DB_PORT、DB_NAME、DB_USERNAME、DB_PASSWORD、 REDIS_HOST、REDIS_PORT。其他变量见环境配置。

export JAVA_HOME=$(/usr/libexec/java_home -v 21) # macOS；其他系统设置对应 JDK 21 路径
pnpm dev:service

通过根命令启动时服务监听 5600，Actuator 监听 5601。Gradle 不会自动读取 .env， 后端变量需要导出到进程环境，或使用 Spring Boot 本地配置。

构建和验证

pnpm openspec:check
pnpm lint:web
pnpm test:web
pnpm build:web
pnpm lint:manage
pnpm test:manage
pnpm build:manage
pnpm build:docs
pnpm lint:service
pnpm build:service

后端 lint:service 执行 Gradle check，包含测试与静态检查。 Vue 前台产物为 packages/web/build/dist-prod/，后台产物为 packages/manage/dist/，后端为 packages/service/alang-bootstrap/build/libs/bootstrap.jar，文档为 docs/.vitepress/dist/。

工作区依赖

仅在根目录执行 install。增加前端依赖使用 pnpm --filter @alang/manage add <包名>； 文档工具使用 pnpm --filter @alang/docs add -D <包名>；根工具使用 pnpm add -Dw <包名>。 Java 依赖在 Gradle 中声明。根 pnpm-workspace.yaml 保留原前端的 Tiptap overrides。

Turbo 缓存前端和文档构建。后端任务禁用 Turbo 缓存，由 Gradle 管理增量构建与缓存； 测试和质量检查每次执行。运行时环境变量透传在根 turbo.json 的 dev 任务维护。

容器构建

后台从仓库根执行 docker build -f packages/manage/Dockerfile -t alang-admin .。 后端先运行 pnpm build:service，然后执行 docker build -t alang-service packages/service。

常见问题

• wuli3 解析失败：检查 Maven Local、settings 中仓库地址与制品访问权限。
• 后台连接失败：检查后端 5600 是否启动；个人代理配置写入 packages/manage/.env.development.local 的 VITE_API_PROXY_TARGET。
• 安装锁文件不匹配：在根目录运行 pnpm install，提交根锁文件，勿恢复子包锁文件。

Vue 源码

上游 ../vue 保留 feature/2.0 分支，工作副本位于 packages/web。 使用 @alang/site 包名，保留上游依赖和启动脚本；包级 dev 转发根 web:dev，Turbo 显示 @alang/site#dev；根工作区登记融云补丁。 导入未包含子锁文件、编辑器/部署元数据与含凭据的 env/.env.test。 需要测试环境凭据时，在本机配置 packages/web/env/.env.test.local，不提交真实凭据。 Vue 默认开发环境仍使用上游远程 API，尚未切换到本地 service。