如何在TypeScript代码库中标记npm包为废弃并添加替代提示？

这个需求完全可行，下面是几种实用的实现方式，能让开发者在VSCode里看到删除线提示和自定义注释：

1. 覆写类型声明（最直观的编辑器提示） #

针对目标npm包创建自定义类型声明文件，给整个包加上@deprecated注释，VSCode会自动识别并给所有导入该包的代码加上删除线，鼠标悬停还会显示提示文字。

步骤：

• 在项目的类型声明目录（比如src/types）下创建X/index.d.ts（X是要废弃的包名）
• 覆写包的模块声明，添加废弃注释：

/** @deprecated Don't use X, use Y instead. */
declare module 'X' {
  // 保留原包的所有类型定义（如果需要），或者直接导出原类型
  export * from 'X';
}

如果原包有具体的导出项，也可以给单个导出单独加注释，细化提示内容。

2. 用ESLint规则强制管控 #

通过ESLint的no-restricted-imports规则，禁止导入目标包，同时给出替代提示。这种方式会在编译或编码阶段抛出警告/错误，适合需要严格管控的场景。

在项目的ESLint配置文件（如.eslintrc.js）中添加：

module.exports = {
  rules: {
    'no-restricted-imports': [
      'warn', // 可以设为'error'强制禁止
      {
        paths: [
          {
            name: 'X',
            message: 'Don\'t use X, use Y instead.'
          }
        ]
      }
    ]
  }
};

3. 封装废弃包做过渡层 #

如果项目里大量使用了该包，直接修改所有导入成本高，可以自己封装一个过渡模块，把原包的导出全部标记为废弃，然后引导团队导入这个过渡模块。

比如创建src/deprecated/X.ts：

/** @deprecated Don't use X, use Y instead. */
import * as X from 'X';
export default X;

// 也可以针对单个导出细化提示
/** @deprecated Don't use X.fetchData, use Y.fetchData instead. */
export const fetchData = X.fetchData;

之后把项目中所有import X from 'X'替换为import X from '@/deprecated/X'，所有使用处都会显示废弃提示。

你可以根据团队的过渡节奏，选择单独使用某一种方案，或者组合多种方式（比如同时用类型声明给编辑器提示，加ESLint规则做强制检查）。

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