TypeScript SDK Enum 运行时 404 问题解决方案

问题描述

在前端项目中引入 TypeScript SDK 后，编译阶段正常，但在浏览器运行时出现 404 Not Found 错误，导致功能异常。

报错示例：

GET http://localhost:3000/src/utils/sdk-dist/types 404 (Not Found)

代码场景：

// 业务代码
import { MeetingType } from '@my-sdk/types'; 
​
console.log(MeetingType.Cycle); // 运行时报错，因为 MeetingType 未被正确加载

---

原因分析

该问题由 TypeScript Enum 的编译特性 与 SDK 模块导出配置 不匹配导致。

1. Enum 包含运行时值

TypeScript 中的 interface 和 type 仅用于编译期类型检查，编译为 JavaScript 后会被移除。而 enum 是一个特例，它既包含类型定义，也包含运行时值。

// TypeScript 源码
export enum Status {
  Active = 1
}
​
// 编译后的 JavaScript
export var Status = {
  Active: 1
};

因此，Enum 必须存在于编译后的 JavaScript 产物中才能被运行时正确引用。

2. 导出方式不当

在 SDK 开发中，如果在入口或中间文件中使用了 export type 语法导出 Enum，TypeScript 编译器会将其视为纯类型进行处理，导致编译后的 JavaScript 产物中缺失了 Enum 对应的对象代码。

错误示例：

// sdk/src/index.ts
// 错误：export type 导致 ./types 下的 Enum 运行时代码被丢弃
export type * from './types'; 

3. 运行时加载失败

当业务代码尝试访问 MeetingType 时：

1. 编译期：TypeScript 编译器从 .d.ts 类型定义文件中找到了 MeetingType，检查通过。
2. 运行时：浏览器尝试加载对应的 JavaScript 模块。由于 SDK 构建产物中缺失了该 Enum 的运行时代码（被 Tree-shaking 移除或未导出），浏览器请求对应资源时无法找到，从而返回 404。

---

解决方案

确保 Enum 被作为“值”正确导出，使其包含在 SDK 的最终构建产物中。

// 错误：仅导出类型
export type { MeetingType } from './meeting';
​
// 正确：导出值
export { MeetingType } from './meeting'; 
// 或
export * from './meeting';

检查构建配置： 检查构建工具（如 Rollup/Webpack）的 sideEffects 配置，确保包含 Enum 的文件未被错误地 Tree-shake 移除。

---

最佳实践

1. 明确导出语法：区分类型与值。对于 Interface 使用 export type，对于 Enum 和 Class 使用 export。
2. 统一入口：SDK 应确保所有公开 API（包括 Enum）均可通过根路径（如 import { ... } from 'my-sdk'）访问，避免引用内部深层路径。