配置说明

配置从 环境变量 读取，实现见服务端 src/config/index.ts（注释中说明了优先级与生产环境注意点）。加载顺序简述如下：

1. 按 NODE_ENV（未设置时视为 development）读取 .env.${NODE_ENV}（例如 .env.development）。
2. 非 development 时，再尝试加载项目根目录 .env。
3. 最后再 dotenv.config() 一次，便于系统环境变量或额外 .env 覆盖。

下文 「未设置」 指：对应环境变量在文件中不写、或留空、且进程环境中也未注入。默认值以仓库当前 src/config/index.ts 为准；若你本地改过代码，以运行时代码为准。

核心配置入口

• 应用与 Colyseus：src/app.config.ts
• 环境变量聚合：src/config/index.ts
• 小游戏：src/config/minigame.ts
• 路由前缀：src/routes/index.ts

服务与数据库

示例（.env.development 片段）：

NODE_ENV=development
PORT=2567

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=your_database
DB_SYNCHRONIZE=true
DB_LOGGING=true

变量	未设置时的含义
NODE_ENV	视为 development。
PORT	2567。
APP_NAME	默认应用名 strataggems-server（展示用，可按项目改名）。
APP_VERSION	1.0.0；同时影响 Swagger 等处未单独配置时的版本展示。
DB_TYPE	mysql。
DB_HOST	localhost。
DB_PORT	3306。
DB_USERNAME	root。
DB_PASSWORD	空字符串（若库要求密码，必须显式配置）。
DB_DATABASE	strataggems（请改成你的库名）。
DB_SYNCHRONIZE	仅当值为字符串 true 时 开启 TypeORM 自动同步；未写或写其它值 → 关闭。生产务必关闭并改用迁移。
DB_LOGGING	仅当值为 true 时 打开 SQL 日志；未设置 → 关闭。
DB_ENTITIES / DB_MIGRATIONS / DB_SUBSCRIBERS	有内置默认 glob；一般不必改，除非目录结构自定义。

说明：部分文档或旧 README 可能写作 DB_SYNC，以 DB_SYNCHRONIZE 为准（与 env.example、.env.development 一致）。

Redis 与 JWT

示例：

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_KEY_PREFIX=strataggems:
REDIS_CONNECT_TIMEOUT=10000
REDIS_LAZY_CONNECT=false

JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=24h
JWT_REFRESH_SECRET=your_refresh_secret_key
JWT_REFRESH_EXPIRES_IN=7d

变量	未设置时的含义
REDIS_HOST	localhost。
REDIS_PORT	6379。
REDIS_PASSWORD	不设置 → 客户端以无密码连接；若 Redis 启用了 requirepass，必须配置。
REDIS_DB	0。
REDIS_KEY_PREFIX	strataggems:（键前缀，多项目共 Redis 时可区分命名空间）。
REDIS_CONNECT_TIMEOUT	10000（毫秒）。
REDIS_LAZY_CONNECT	仅当值为 true 时 懒连接；未设置 → false（启动期即尝试连接，行为以 ioredis 为准）。
JWT_SECRET	使用代码内 开发用占位字符串（生产必须改，否则严重不安全）。
JWT_EXPIRES_IN	24h（字符串形式，供 jsonwebtoken 等使用；其它模块若按秒解析，请以该模块实现为准）。
JWT_REFRESH_SECRET	使用代码内 开发用占位（生产必须改）。
JWT_REFRESH_EXPIRES_IN	7d。

匹配、进房鉴权、世界聊天跨实例等依赖 Redis；未启动 Redis 或地址错误时，相关功能会失败或降级（参见各专题文档）。

房间、聊天与压测

示例：

COLYSEUS_MAX_CLIENTS=100
CHAT_ROOM_MAX_CLIENTS=5000
CHAT_WORLD_REDIS_CHANNEL=colyseus:chat:world
LOADTEST_ROOM_MAX_CLIENTS=10000
LOADTEST_ROOM_ENABLED=true

COLYSEUS_PING_INTERVAL=3000
COLYSEUS_PING_MAX_RETRIES=3

变量	未设置时的含义
COLYSEUS_MAX_CLIENTS	全局预留上限 100（单房上限等以房间类型为准，见 app.config）。
CHAT_ROOM_MAX_CLIENTS	聊天房 Room.maxClients 默认目标 5000，实际会限制在 1～65535 之间。
CHAT_WORLD_REDIS_CHANNEL	世界频道 Pub/Sub 使用 colyseus:chat:world；多实例必须一致。
LOADTEST_ROOM_MAX_CLIENTS	压测房单房上限默认 10000（同样裁剪到合法范围）。
LOADTEST_ROOM_ENABLED	仅当值为字符串 false 时 关闭压测房；未设置或其它值 → 视为开启（与「默认允许压测房」一致）。生产请显式设为 false。
COLYSEUS_PING_INTERVAL	3000（毫秒）。
COLYSEUS_PING_MAX_RETRIES	3。

对局重连窗口（game_room）由 MATCH_RECONNECT_WINDOW_MS 控制，未设置 时一般为 15000 毫秒（见 帧同步与游戏房）。

Swagger（可选）

变量	未设置时的含义
SWAGGER_ENABLED	仅当值为 false 时 关闭；未设置 → 开启。
SWAGGER_PATH	/api-docs。
SWAGGER_TITLE / SWAGGER_DESCRIPTION / SWAGGER_VERSION	有中文默认文案；SWAGGER_VERSION 还可回退到 APP_VERSION。
SWAGGER_SERVER_URL	默认 http://localhost:${PORT}。
SWAGGER_CONTACT_*	未设置则联系信息为空块，不影响启动。

实践建议

• 生产环境将 DB_SYNCHRONIZE 设为 false，用迁移管理表结构。
• JWT_SECRET、JWT_REFRESH_SECRET、数据库与 Redis 密码使用高强度随机值。
• 多实例部署：Redis 必达，且 CHAT_WORLD_REDIS_CHANNEL 各节点一致。
• 生产将 LOADTEST_ROOM_ENABLED=false，避免误暴露无鉴权压测房。

延伸阅读

• 安装指南
• 项目结构（src/config 与 app.config 关系）