使用--declaration生成d.ts时const命名空间JSDocs丢失如何解决？

这是TypeScript目前版本（5.x及更早）的原生行为：当你使用const声明普通对象并通过@namespace标记为命名空间时，tsc的.d.ts生成逻辑不会将绑定在const变量上的JSDoc注释透传到最终生成的declare namespace节点上，仅会保留对象内部成员的注释。

• 首先确认tsconfig.json中的compilerOptions.removeComments配置为false，该配置开启时会全局移除所有编译产物的注释，包括d.ts文件内的注释
• 确认已开启compilerOptions.allowJs、compilerOptions.declaration两个必要配置

方案1：修改原有JS代码的命名空间写法（最推荐） #

将const定义的对象形式命名空间改为标准JSDoc兼容的namespace写法，tsc可直接完整保留所有注释：

/**
 * Foo namespace
 * @namespace
 */
namespace Foo {
    /** Test function */
    export function foo() {}
    /** Test property */
    export const bar = 1
}

该写法生成的d.ts和你预期的输出完全一致。

方案2：新增补充声明文件（无需修改原有业务代码） #

如果不想改动原有JS代码，可以在项目中新增一个额外的.d.ts文件，手动补充命名空间的顶层注释，TypeScript会自动合并同名命名空间的声明：

/**
 * Foo namespace
 * @namespace
 */
declare namespace Foo {}

然后正常执行tsc生成声明即可，最终产物会同时包含你补充的顶层注释和自动生成的成员定义。

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