t-comm/lib/cocos/env/env.d.ts

专业、稳定、纯粹的工具库

/**
 * 环境切换（test / prod）
 *
 * 设计要点：
 *   1. 仅维护 test / prod 两个环境（后续如需扩展再说）。
 *   2. 默认环境根据微信小程序/小游戏版本自动判定：
 *        - envVersion === 'release'  → 'prod'
 *        - 其他（develop / trial / 非小程序环境） → 'test'
 *   3. 构建期可通过 `globalThis.__COCOS_BUILD_NETWORK_ENV__` 注入默认值，
 *      优先级高于 wx AccountInfo 推断但低于用户手动切换（持久化存储）。
 *      典型场景：CI/headless --env prod 构建时，开发工具/体验版中仍走正式域名。
 *   4. 用户通过 wx.__pmdSetEnv__('prod' | 'test') 手动切换后，会写入持久化存储，
 *      下次启动时优先读取存储值，不再受小程序版本影响（直到再次切换）。
 *   5. 切换后默认自动重启小游戏（wx.restartMiniProgram）/ 浏览器（location.reload），
 *      让新环境立刻生效。
 *   6. 全局调试函数优先挂到 wx 对象上（小游戏环境下 console 拿不到 globalThis），
 *      没有 wx 时回退到 globalThis。
 *
 * 优先级（从高到低）：
 *   用户手动切换（持久化存储） > globalThis.__COCOS_BUILD_NETWORK_ENV__ > wx AccountInfo 推断
 */
import type { ICocosLoginInfoStorage } from '../network/types';
/** 当前支持的环境枚举 */
export type Env = 'test' | 'prod';
/** 各环境对应的服务端域名（不带协议、不带末尾斜杠） */
export type EnvDomainMap = Record<Env, string>;
/** 默认存储 key */
export declare const DEFAULT_ENV_STORAGE_KEY = "pmd_api_cocos_env";
/** 构建期注入的全局变量 key：项目通过 globalThis[__COCOS_BUILD_NETWORK_ENV__] 设置默认环境 */
export declare const GLOBAL_BUILD_ENV_KEY = "__COCOS_BUILD_NETWORK_ENV__";
/** 默认全局调试函数名 */
export declare const DEFAULT_GLOBAL_SET_ENV = "__pmdSetEnv__";
export declare const DEFAULT_GLOBAL_GET_ENV = "__pmdGetEnv__";
/**
 * 推断"未手动设置过环境"时的默认 env：
 *   1. globalThis.__COCOS_BUILD_NETWORK_ENV__（构建期注入）
 *   2. 小程序正式版（release） → 'prod'
 *   3. 其他情况              → 'test'
 */
export declare function inferDefaultEnv(): Env;
/**
 * 读取当前生效的环境：
 *   - 优先读取持久化存储中的手动切换值（与 createEnvSwitcher 内部 readEnv 保持一致）
 *   - 没有持久化值时回退到 inferDefaultEnv()（含 globalThis 构建注入）
 */
export declare function readEnv(storageKey?: string, storage?: ICocosLoginInfoStorage): Env;
export declare function isTestEnv(storageKey?: string, storage?: ICocosLoginInfoStorage): boolean;
export interface IEnvSwitcherOptions {
    /** 各环境对应的服务端域名（不带协议、不带末尾斜杠） */
    svrdomain: EnvDomainMap;
    /** 持久化 key，默认 'pmd_api_cocos_env' */
    storageKey?: string;
    /** 自定义存储（默认 cocos sys.localStorage → 浏览器 localStorage → 内存） */
    storage?: ICocosLoginInfoStorage;
    /** 切换时是否自动重启（restartMiniProgram / location.reload），默认 true */
    autoRestart?: boolean;
    /**
       * 全局 setter 函数名，默认 '__pmdSetEnv__'。传 false 关闭挂载。
       * 会优先挂到 wx 上（如 wx.__pmdSetEnv__），没有 wx 时回退到 globalThis。
       */
    globalSetEnvName?: string | false;
    /**
       * 全局 getter 函数名，默认 '__pmdGetEnv__'。传 false 关闭挂载。
       * 会优先挂到 wx 上（如 wx.__pmdGetEnv__），没有 wx 时回退到 globalThis。
       */
    globalGetEnvName?: string | false;
    /** 切换成功后回调（持久化已完成、重启之前） */
    onChange?: (next: Env, prev: Env) => void;
}
export interface IEnvSwitcher {
    /** 当前环境 */
    getEnv(): Env;
    /** 当前环境对应的域名（不带协议） */
    getDomain(): string;
    /** 当前环境对应的 baseUrl（含 https://） */
    getBaseUrl(): string;
    /**
       * 切换环境。autoRestart 不传时取构造时配置（默认 true）。
       * 非法 env 会被忽略并打 warn。
       */
    setEnv(env: Env, autoRestart?: boolean): void;
    isTestEnv(): boolean;
}
/**
 * 创建一个环境切换器。
 */
export declare function createEnvSwitcher(options: IEnvSwitcherOptions): IEnvSwitcher;