如何用TypeScript确保字符串指向有效图片路径？

在React+TypeScript项目里，直接用string类型定义图片路径会导致TS无法区分普通字符串和require()/import返回的有效图片路径，下面提供几种可行的解决方案：

方案1：为图片文件添加模块声明（推荐） #

TypeScript默认不知道图片文件的类型，我们可以通过自定义模块声明，让TS识别图片导入的返回值类型：

1. 在项目根目录或src文件夹下创建declarations.d.ts（如果已有就直接编辑），添加对应图片格式的声明：

// 声明PNG图片模块
declare module '*.png' {
  const src: string;
  export default src;
}

// 声明JPG/JPEG图片模块
declare module '*.jpg' {
  const src: string;
  export default src;
}

// 根据项目需求添加其他格式，比如SVG、WebP等
declare module '*.svg' {
  const src: string;
  export default src;
}

2. 调整类型定义和导入方式：
   把Obj的img类型改为图片模块的导入类型，或者用联合类型覆盖所有支持的格式：

// 定义支持的图片路径类型
type ValidImagePath = typeof import('*.png') | typeof import('*.jpg') | typeof import('*.svg');

type Obj = {
  img: ValidImagePath;
};

// 正确写法：用ES模块导入图片
import UserAvatar from './../avatar.png';
const obj1: Obj = {
  img: UserAvatar
}; // TS正常通过检查

// 错误写法：普通字符串会触发TS报错
const obj2: Obj = {
  img: './../avatar.png'
};

const obj3: Obj = {
  img: '随便写的字符串'
};

这种方式完全符合React和TypeScript的最佳实践，不需要额外的类型断言，TS能自动校验图片路径的有效性（甚至能检查文件是否存在）。

方案2：用品牌类型（Branded Type）区分普通字符串和图片路径 #

如果你的项目必须使用require()，可以用品牌类型给有效图片路径打一个“标记”，让TS区分普通字符串和require()返回的路径：

// 定义品牌类型：给string添加唯一的标识属性
type ImagePath = string & { __isValidImage: never };

// 封装一个安全的require方法，返回品牌类型
function getImagePath(path: string): ImagePath {
  return require(path) as ImagePath;
}

// 调整Obj的类型
type Obj = {
  img: ImagePath;
};

// 正确写法
const obj1: Obj = {
  img: getImagePath('./../avatar.png')
};

// 错误写法：普通字符串无法赋值给ImagePath类型
const obj2: Obj = {
  img: './../avatar.png'
};

const obj3: Obj = {
  img: '随便写的字符串'
};

品牌类型的核心是利用TS的结构类型系统，通过一个不存在的私有属性（比如__isValidImage）来区分普通字符串和我们定义的图片路径类型，只有通过getImagePath函数返回的值才会被TS认为是有效的图片路径。

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