feat(framework): config 调试 serverOverride(全链路+游戏服连本地)

- DebugProfile 加 serverOverride：debug 抓远程配置走全链路后把连接地址覆盖为此
- staging profile 加 serverOverride=ws://127.0.0.1:3088（联调本地测试服）
- release 一律忽略 serverOverride，用远程解析结果
- 同步指南

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cocoscreator_projects/YouleNexus/assets/framework/config/bootstrap.ts

@@ -72,7 +72,9 @@ export async function resolveBootstrap(opts: BootstrapOptions): Promise<Bootstra
     throw new ConfigFetchError(`远程配置抓取失败: ${url}`);
   }
 
-  const servers = resolveServers(config, identity);
+  const resolved = resolveServers(config, identity);
+  // debug 可把连接地址显式覆盖为本地测试服（仍走完整远程配置链路）；release 一律用远程解析结果。
+  const servers = isDebug && profile.serverOverride ? [profile.serverOverride] : resolved;
   if (!servers.length) {
     throw new ConfigFetchError(`远程配置未给出可用服务器地址: ${url}`);
   }

cocoscreator_projects/YouleNexus/assets/framework/config/profiles.ts

@@ -13,8 +13,9 @@ export interface DebugAccount {
 
 export interface DebugProfile {
   name: string;
-  server?: string;                      // 显式 ws 调试服地址（给定则跳过远程抓取）
+  server?: string;                      // 显式 ws 调试服地址（给定则跳过远程抓取，纯直连）
   gameserver?: string;                  // 远程配置 txt URL（不含防缓存串）
+  serverOverride?: string;              // debug：抓远程配置走全链路后，把连接地址覆盖为此（联调本地游戏服用）
   identity?: Partial<ChannelIdentity>;  // 调试用渠道身份覆盖
   account?: DebugAccount;               // 调试用登录账号（仅 debug 模式生效）
   isDebugger?: boolean;                 // 收发包日志开关（替代旧 Game_Config.Debugger.isDebugger）
@@ -30,9 +31,10 @@ export const PROFILES: Record<string, DebugProfile> = {
   staging: {
     name: 'staging',
     gameserver: STAGING_GAMESERVER,
+    serverOverride: 'ws://127.0.0.1:3088',   // 走 staging 配置全链路，但游戏服连本地测试服
     isDebugger: true,
     // 调试登录账号：联调前替换为真实测试账号（openid 必填）。仅 debug 模式生效。
-    account: { openid: 'REPLACE_ME_test_openid', nickname: '测试号', avatar: '', sex: 0, province: '', city: '', unionid: '' },
+    account: { openid: 'REPLACE_ME_test_openid', nickname: '测试号', avatar: 'https://gips3.baidu.com/it/u=4028841722,3177937756&fm=3074&app=3074&f=PNG?w=2048&h=2048', sex: 0, province: 'testprovince', city: 'testcity', unionid: 'test_unionid' },
   },
   local:   { name: 'local',   server: 'ws://127.0.0.1:3088',  isDebugger: true },
 };

cocoscreator_projects/framework-tests/config/bootstrap.test.ts

@@ -89,6 +89,20 @@ test('release：原生身份仍生效（URL 的 999 无效）', async () => {
   assert.equal(r.identity.channelid, 'NC');
 });
 
+test('debug + serverOverride：走远程全链路但连接地址覆盖为本地', async () => {
+  const fetcher = fetcherReturning(REMOTE);   // REMOTE.player_server_tcp = 5.5.5.5:5000
+  const r = await resolveBootstrap({ mode: 'debug', win: {}, search: '?profile=staging', fetcher, isNative: false });
+  assert.deepEqual(r.servers, [PROFILES.staging.serverOverride]); // 覆盖为 profile.serverOverride
+  assert.ok(r.rawConfig);                      // 远程配置仍抓取（全链路）
+  assert.equal(fetcher.calls.length, 1);
+});
+
+test('release：serverOverride 不生效（强制 prod，用远程解析地址）', async () => {
+  const fetcher = fetcherReturning(REMOTE);
+  const r = await resolveBootstrap({ mode: 'release', win: {}, search: '?profile=staging', fetcher, isNative: true });
+  assert.deepEqual(r.servers, ['ws://5.5.5.5:5000']); // prod 无 override，用远程解析
+});
+
 test('debug：account 来自当前 profile', async () => {
   const fetcher = fetcherReturning(REMOTE);
   const r = await resolveBootstrap({ mode: 'debug', win: {}, search: '?profile=staging', fetcher, isNative: false });