diff --git a/cocoscreator_projects/YouleNexus/assets/framework/config/runtime-mode.ts b/cocoscreator_projects/YouleNexus/assets/framework/config/runtime-mode.ts
new file mode 100644
index 0000000..41328f9
--- /dev/null
+++ b/cocoscreator_projects/YouleNexus/assets/framework/config/runtime-mode.ts
@@ -0,0 +1,20 @@
+export type RuntimeMode = 'debug' | 'release';
+
+/**
+ * 手动覆盖运行模式。
+ * null  = 自动跟随构建类型（推荐，发布前保持 null）。
+ * 'debug' / 'release' = 强制该模式（release 包里临时调试，或编辑器预览里验证正式行为）。
+ */
+export const MODE_OVERRIDE: RuntimeMode | null = null;
+
+/**
+ * 解析运行模式：override 优先，否则由是否 debug 构建决定。
+ * isDebugBuild 由调用方读 Cocos 全局 DEBUG 传入（typeof DEBUG !== 'undefined' ? DEBUG : true）。
+ */
+export function resolveRuntimeMode(
+  isDebugBuild: boolean,
+  override: RuntimeMode | null = MODE_OVERRIDE,
+): RuntimeMode {
+  if (override) return override;
+  return isDebugBuild ? 'debug' : 'release';
+}
diff --git a/cocoscreator_projects/framework-tests/config/runtime-mode.test.ts b/cocoscreator_projects/framework-tests/config/runtime-mode.test.ts
new file mode 100644
index 0000000..b3138cf
--- /dev/null
+++ b/cocoscreator_projects/framework-tests/config/runtime-mode.test.ts
@@ -0,0 +1,16 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveRuntimeMode } from '../../YouleNexus/assets/framework/config/runtime-mode.ts';
+
+test('override 优先于构建类型', () => {
+  assert.equal(resolveRuntimeMode(true, 'release'), 'release');
+  assert.equal(resolveRuntimeMode(false, 'debug'), 'debug');
+});
+
+test('无 override：debug 构建 → debug', () => {
+  assert.equal(resolveRuntimeMode(true, null), 'debug');
+});
+
+test('无 override：release 构建 → release', () => {
+  assert.equal(resolveRuntimeMode(false, null), 'release');
+});