如何让TypeScript自动生成含完整声明的.d.ts导出内容？

当然可以实现！要让TypeScript输出包含完整注释的声明文件，核心是给源码添加规范的JSDoc注释，再配合正确的TypeScript编译配置，就能自动生成带描述的.d.ts文件。下面是具体步骤：

1. 给源码添加JSDoc注释 #

在你的TypeScript源码中，给类型、函数、属性逐一添加清晰的JSDoc注释，包括描述、参数说明、返回值说明甚至默认值标注。比如针对你的代码：

/**
 * 正则表达式解析器的配置选项
 */
export type IOptions = {
  /**
   * 是否允许使用非原生的斜杠作为正则分隔符
   * @default false
   */
  allowNonNativeSlash?: boolean;
  /**
   * 是否允许使用非标准的正则标志位
   * @default false
   */
  allowNonNativeFlags?: boolean;
  /**
   * 解析失败时是否抛出错误，否则返回兼容格式的结果
   * @default false
   */
  throwError?: boolean;
};

/**
 * 解析正则表达式字符串，提取出源码、标志位等核心信息
 * @param str 待解析的正则字符串（例如 "/hello-world/i"）
 * @param options 自定义解析配置
 * @returns 解析后的结果对象，包含以下字段
 */
export function parseRegularExpressionString(
  str: string,
  options?: IOptions
): {
  /** 正则表达式的核心源码（不含分隔斜杠和标志位） */
  source: string;
  /** 正则表达式的标志位（例如 "gi"） */
  flags: string;
  /** 解析到的正则分隔斜杠（例如 "/"） */
  slash: string;
  /** 原始输入的完整字符串 */
  input: string;
} {
  // 你的业务实现代码
  return { source: '', flags: '', slash: '', input: str };
}

2. 配置TypeScript编译参数 #

修改你的tsconfig.json，确保开启声明文件生成并保留注释：

{
  "compilerOptions": {
    "target": "ES2020", // 根据你的项目需求调整
    "module": "ESNext",
    "declaration": true, // 启用.d.ts文件生成
    "stripComments": false, // 关键：不要移除注释，确保JSDoc被保留到声明文件
    "outDir": "./dist", // 声明文件输出目录
    "strict": true // 可选，开启严格模式提升类型质量
  },
  "include": ["src/**/*"] // 指定要编译的源码目录
}

3. 编译生成带注释的.d.ts #

执行tsc命令编译后，你会在outDir指定的目录下得到带完整注释的声明文件，效果如下：

/**
 * 正则表达式解析器的配置选项
 */
export declare type IOptions = {
    /**
     * 是否允许使用非原生的斜杠作为正则分隔符
     * @default false
     */
    allowNonNativeSlash?: boolean;
    /**
     * 是否允许使用非标准的正则标志位
     * @default false
     */
    allowNonNativeFlags?: boolean;
    /**
     * 解析失败时是否抛出错误，否则返回兼容格式的结果
     * @default false
     */
    throwError?: boolean;
};
/**
 * 解析正则表达式字符串，提取出源码、标志位等核心信息
 * @param str 待解析的正则字符串（例如 "/hello-world/i"）
 * @param options 自定义解析配置
 * @returns 解析后的结果对象，包含以下字段
 */
export declare function parseRegularExpressionString(str: string, options?: IOptions): {
    /** 正则表达式的核心源码（不含分隔斜杠和标志位） */
    source: string;
    /** 正则表达式的标志位（例如 "gi"） */
    flags: string;
    /** 解析到的正则分隔斜杠（例如 "/"） */
    slash: string;
    /** 原始输入的完整字符串 */
    input: string;
};

额外注意事项 #

• 如果你的项目使用打包工具（如Rollup、Webpack），要确保打包插件不会移除注释。比如使用rollup-plugin-typescript2时，需要在配置中覆盖stripComments为false；
• 尽量使用标准的JSDoc标签（如@param、@returns、@default），TypeScript会更好地识别并转换到声明文件中；
• 若只需要生成声明文件而不需要编译JS，可以开启emitDeclarationOnly: true选项。

内容的提问来源于stack exchange，提问作者bluelovers