TuffNexus
|Docs
文档/Core App 启动链路与运行时变量参考
通用开发

Core App 启动链路与运行时变量参考

Core App 启动链路与运行时变量参考

更新时间：2026-05-12 范围：apps/core-app/src 中 process.env / import.meta.env 的实际引用

启动异常梳理（本次 1+2 变更）

1) Assistant 模块 gate（已改）

  • 现状：TUFF_ENABLE_ASSISTANT_EXPERIMENT 未开启时，Assistant 不再走“optional failed”路径。
  • 行为：直接走 shouldSkip，日志为 Skip Assistant module: TUFF_ENABLE_ASSISTANT_EXPERIMENT disabled。
  • 效果：不会再出现误导性的 Optional module failed to load: Symbol(Assistant) 告警。

2) dev.source 探活 + 本地降级（已改）

  • 现状：DevPluginLoader 先请求远端 manifest.json 作为探活。
  • 远端失败时：
    • 自动回退到本地 manifest.json + 本地 README/资产；
    • 运行时强制 dev.source=false（仅当前进程，不落盘）；
    • 记录 DEV_SOURCE_FALLBACK_LOCAL（warning）。
  • 仅当“远端失败 + 本地也不可用”时，才记录 REMOTE_MANIFEST_FAILED（error）。

插件 Issue Code 速查（含 DEV_SOURCE_FALLBACK_LOCAL）

Code默认级别作用
MISSING_MANIFESTerror插件目录缺少 manifest.json
INVALID_MANIFEST_JSONerror本地或远端 manifest 无法解析
NAME_MISMATCHerrormanifest.name 与目录名不一致
MANIFEST_MISSING_NAMEerror缺少 name
MANIFEST_MISSING_VERSIONwarning缺少 version（默认 0.0.0）
CATEGORY_MISSINGerrorsdkapi 达门槛但未声明 category
SDKAPI_BLOCKEDerrorsdkapi 缺失、非法、未受支持或低于最低门槛，插件会被直接阻断
PERMISSION_MISSINGwarning缺少必需权限授权
UNKNOWN_PERMISSION_IDSwarning声明了未知权限 ID
INVALID_FEATURE_COMMANDSwarningfeature.commands 结构不合法
OMNI_TRANSFER_SDK_TOO_LOWwarning声明 omniTransfer 但 sdkapi 不满足
DUPLICATE_PLUGIN_NAMEerror插件名冲突
LOADER_FATALerror加载器阶段致命异常
DEV_MODE_ACTIVEwarning插件当前运行在 dev 模式
DEV_ADDRESS_INVALIDerrordev.address 非法
DEV_SOURCE_DISABLED_IN_PACKAGEDwarning打包环境自动禁用 dev.source
DEV_SOURCE_FALLBACK_LOCALwarning远端探活失败后回退本地资产
REMOTE_MANIFEST_FAILEDerror远端 manifest 失败且本地回退也失败
DEV_SERVER_DISCONNECTEDwarningdev server 健康检查断连
LIFECYCLE_SCRIPT_FAILEDerrorindex.js 生命周期脚本执行失败
RUNTIME_ERRORerror运行期生命周期/调用异常
AUTO_DISABLED_EXCESSIVE_ERRORSerror短时错误过多触发自动停用
INVALID_VIEW_PATHerrorinteraction path 非法
PROTOCOL_NOT_ALLOWEDerror生产环境禁止远端 http/https view
WIDGET_UNSUPPORTED_TYPEerrorwidget 类型不支持
WIDGET_INVALID_DEPENDENCYerrorwidget 依赖不允许
WIDGET_COMPILE_FAILEDerrorwidget 编译失败

环境变量全量说明（逐项）

A. 业务开关 / 可配置项

变量作用主要读取位置
ELECTRON_RENDERER_URLdev 模式渲染入口 URL（主窗口/CoreBox/OmniPanel/MetaOverlay 等）src/main/core/touch-app.ts、src/main/utils/renderer-url.ts
NODE_ENVdev/test/prod 行为判断（日志、分析、store API）多处（analytics/logger/sentry/store）
BUILD_TYPE构建类型（Sentry environment/release 等）src/main/modules/sentry/*、app-provider.ts
TUFF_ENABLE_ASSISTANT_EXPERIMENTAssistant 模块是否进入启动编排src/main/index.ts
TUFF_ENABLE_RENDERER_OVERRIDE是否允许 renderer override 包生效src/main/core/touch-app.ts、src/main/modules/update/update-system.ts
TUFF_NEXUS_BASE_URLCore App 运行时 Nexus API 基地址显式覆盖；优先级高于设置页 server modepackages/utils/env、Core App Nexus runtime resolver
TUFF_DISABLE_NATIVE_OCR关闭本地 OCR providersrc/main/modules/ai/intelligence-config.ts
TUFF_RELEASE_API_URL构建验签元数据 API 基地址覆盖src/main/modules/build-verification/index.ts
TUFF_BUILD_SIGNATURE_URL构建验签签名文件 URL 强制覆盖src/main/modules/build-verification/index.ts
TUFF_BUILD_SIGNATURE_KEY_URL构建验签公钥 URL 强制覆盖src/main/modules/build-verification/index.ts
TUFF_UPDATE_SIGNATURE_KEY_URL更新包验签公钥 URL（优先）src/main/utils/release-signature.ts
TUFF_UPDATE_SIGNATURE_PUBLIC_KEY_URL更新包验签公钥 URL（兼容别名）src/main/utils/release-signature.ts
TALEX_EVERYTHING_SDK_PATHWindows Everything SDK addon 自定义路径src/main/modules/box-tool/addon/files/everything-provider.ts
TALEX_FILE_PROVIDER_EXTRACT_ICONSFileProvider 图标提取开关（默认开）src/main/modules/box-tool/addon/files/file-provider.ts

B. 启动期内部注入变量（非外部配置）

变量作用写入位置
APP_VERSION运行时版本号（缺省时从 package.json 注入）src/main/polyfills.ts
DIST主进程运行目录src/main/polyfills.ts
PUBLIC公共资源目录（packaged/dev 分流）src/main/polyfills.ts
DEBUGdebug.talex 文件触发的日志调试开关src/main/polyfills.ts
ELECTRON_DISABLE_SECURITY_WARNINGS关闭 Electron 安全警告输出src/main/polyfills.ts
WS_NO_UTF_8_VALIDATE禁用 ws 可选 utf-8-validate addonsrc/main/index.ts
WS_NO_BUFFER_UTIL禁用 ws 可选 bufferutil addonsrc/main/index.ts

C. 系统环境变量（只读依赖）

变量作用主要读取位置
HOMEmacOS/Linux 扫描用户应用目录src/main/modules/box-tool/addon/apps/app-scanner.ts
LANGLinux 应用名称本地化解析src/main/modules/box-tool/addon/apps/linux.ts
LOCALAPPDATAWindows Everything/App 扫描路径everything-provider.ts、app-scanner.ts
PROGRAMFILESWindows 安装路径扫描everything-provider.ts、network-service.ts、file-protocol/index.ts
PROGRAMFILES(X86)Windows x86 安装路径扫描同上
SystemRootWindows 系统目录探测network-service.ts、file-protocol/index.ts
USERPROFILEWindows 管理员路径特征判断system/permission-checker.ts
WINDIRWindows 临时写权限检测路径system/permission-checker.ts
TERM托盘“在终端中打开”候选命令modules/tray/tray-menu-builder.ts
TERMINAL同上（备用）modules/tray/tray-menu-builder.ts

D. 渲染层构建变量（Vite）

变量作用主要读取位置
import.meta.env.DEV前端 dev 分支（日志/调试 UI）renderer/src/utils/dev-log.ts 等
import.meta.env.MODE前端模式判断（如 about 页显示）renderer/src/views/base/settings/SettingAbout.vue

可清理变量候选（先列出，不直接删除）

当前暂无待清理候选（前述高/中/低优先项已全部完成收敛）。

Nexus Runtime API 服务器解析

  • Core App 运行时 API 统一由 packages/utils/env.resolveTuffNexusBaseUrl() 解析，唯一外部覆盖变量是 TUFF_NEXUS_BASE_URL。
  • 解析优先级固定为：TUFF_NEXUS_BASE_URL 显式覆盖 > 设置页“运行时 API 服务器”为 local > 官方地址 https://tuff.tagzxia.com。
  • local 模式默认地址为 http://localhost:3200，但不会再因为 dev/unpackaged 自动启用；必须由设置页 local 或 TUFF_NEXUS_BASE_URL 显式指定。
  • 官网、文档、Dashboard、更新源等外链默认值继续使用官方线上地址，不跟随运行时 API server mode。

已完成清理项

  • trace-warnings：已从 src/main/polyfills.ts 移除运行时 process.env 写入（2026-03-23）。
  • unhandledrejections：已从 src/main/polyfills.ts 移除运行时 process.env 写入（2026-03-23）。
  • VITE_DEV_SERVER_URL（main 侧 fallback）：已移除 AppProvider fallback 读取，统一为 ELECTRON_RENDERER_URL（2026-03-23）。
  • TALEX_WORKFLOW_DEBUG：已移除 TPEX Provider 固定 SID 调试开关与对应写盘逻辑（2026-03-23）。
  • TUFF_RELEASE_SIGNATURE_KEY_URL / TUFF_RELEASE_SIGNATURE_PUBLIC_KEY_URL：已从签名公钥 URL 解析中移除兼容别名，统一 TUFF_UPDATE_*（2026-03-23）。
  • TUFF_OMNIPANEL_SMOKE：已移除启动期 OmniPanel 冒烟探针 env gate 与对应逻辑（2026-03-23）。
  • USE_LOCAL_NEXUS：已移除 PluginStoreService 的本地 Nexus env 特判，统一走 getTpexApiBase()（2026-03-23）。
  • VITE_NEXUS_URL / NEXUS_API_BASE / NEXUS_API_BASE_LOCAL / TPEX_API_BASE / AUTH_ORIGIN / TUFF_LOCAL_BASE_URL：已停止作为 Core App runtime API 地址解析输入，统一迁移到 TUFF_NEXUS_BASE_URL（2026-05-12）。
Dev
上一章Manifest 参考下一章 常用代码片段