常见问题

这里汇总了开发者在使用 TechUI 过程中最常遇到的技术与授权问题。如果您遇到的问题未在此列出，请尝试使用 tuiCoreInfo() 查看详细错误代码，或联系技术支持。

环境与部署

Q: 安装后提示缺少依赖包，如 @techui/utils 或 @techui/themes？

A: 理论上 TechUI 生态包会自动安装，若失败需手动补全。 通常在安装 @techui/scifi 等核心库时，npm/yarn 会根据依赖关系自动安装相关的生态包。但在某些镜像服务器（如 cnpm、公司私有源）更新延迟的情况下，可能会导致依赖缺失。

解决方案：

1. 手动安装：发现缺失后，请根据报错手动执行 npm install @techui/utils @techui/themes 等命令。
2. 版本匹配：请务必检查您当前安装的核心组件库（如 @techui/scifi）中 package.json 所声明的依赖版本。
   • 建议：若您使用的是最新版本核心库，直接安装相关依赖的 latest 版本即可。

已知特定环境说明：

• 在使用pnpm安装的时候，确实出现了关联依赖无法安装的问题。
• 使用npm安装的时候，目前并未发现。

---

Q: 遇到异常报错，无从下手调试？

A: 可能是因为 Vite 的依赖预构建 (Dependency Optimization)所致，建议将 TechUI 核心库及部分生态包排除在预构建之外。

由于 TechUI 包含 Wasm 核心，Vite 的默认预构建机制并不会处理 Wasm 文件。

解决方案： 在 vite.config.ts 中配置 optimizeDeps.exclude：

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: [
      "@techui/prime", 
      // 根据您当前选择的组件库进行配置 
      // 如：@techui/prime, @techui/admin, @techui/base, @techui/scifi
      "@techui/utils",
      "@techui/themes"
      // 其他生态包...
    ]
  }
})

已知特定环境说明：

• Vite 7.3.1 + TS 环境：已确认必须将 @techui/themes 添加到 exclude 名单中，否则会导致异常报错。
• Vite 7.1.7 环境：测试无需特殊配置 @techui/themes 即可正常运行。

如遇到无法解释的运行时报错，请优先尝试将相关的 @techui/* 包均列入 exclude 名单。

授权与密钥

Q: 授权密钥 (License Key) 直接写在前端代码里安全吗？

A: 相对安全。 TechUI 采用的是 “零信任” 验证架构。

1. 无法隐藏：作为纯前端方案，Key 必然暴露在代码中。
2. 难以利用：Key 本身只是一个加密凭证。没有 Wasm 内部的私钥算法配合，攻击者拿到 Key 也无法生成新的授权，也无法解密核心功能。

此外，如果您的实例要部署到公网环境，建议联系管理员给许可证绑定了域名，此时Key的泄露也并不会导致滥用。

默认情况下，并不会对许可证进行 域名绑定 或者 开启仅本地部署限制。

Q: 开发许可证 过期了会发生什么？

A: 系统将触发熔断。 如果您的许可证为开发许可证，请务必关注控制台的 距离到期 [XX] 天 提示。

开发与集成

Q: 为什么不支持按需引入 (Tree-shaking)？

A: 基于架构与安全的权衡。 TechUI 的核心是一个完整的 Wasm 二进制模块，无法像 JS 代码那样拆分。同时，全量打包也是为了保护核心算法不被逆向分析。详情请参阅 [不支持按需引入] 章节。

Q: 我可以同时使用 Base 和 Scifi 两个库吗？

A: 不可以。 遵循 “单核心原则”，同一项目中严禁引入多个 TechUI 核心库，否则会导致 Wasm 上下文冲突。如果您需要两者的功能，请升级至 Prime (旗舰版)。

商业与合规

Q: 我购买了商业许可证，可以给我的客户分发吗？

A: 可以，但需遵循子许可规则。 商业许可证包含商业分发权。您需要在 TechUI 开发者后台为您交付的每一个客户项目生成独立的 子许可证 (Sub-License)。严禁直接将您的母许可证密钥（Master Key）交给客户。

B: 其他许可证，请以客户的名义购买和生成许可

C: 免费版无任何限制，可以随意分发

Q: 为什么在某些国家无法使用？

A: 地理围栏限制。 基于合规性与反诈策略，我们对缅甸、柬埔寨等特定区域进行了限制。如您的业务为当地合规企业，请联系商务申请白名单豁免。

特殊问题

Q: 为什么触发注销事件的时候，会提示告警信息。

在Prime或者Admin组件库，触发注销的时候，提示告警信息：TDB: Database deletion is blocked, make sure all connections are closed !

A: 因为Prime和Admin的导航菜单，采用了浏览器自身的IndexedDB数据库，如果开启了两个同地址的浏览器标签，则在注销其中一个的时候，IndexedDB数据库无法关闭连接导致的错误。