Create React App使用自定义.d.ts时出现Webpack报错如何解决

核心错误原因 #

.d.ts类型声明文件仅在TypeScript类型校验阶段生效，不会被编译为可执行的运行时代码。
你当前代码里写了import someFunction from 'myTypes'，Webpack打包时会将其作为真实运行时依赖，按照模块解析规则去node_modules、源码目录下找对应的JS/TS实体文件，找不到就会抛出你看到的「Field 'browser' doesn't contain a valid alias configuration」「模块不存在」类报错。
你写的declare module 'myTypes'属于环境模块声明，作用是给已经存在的、缺少类型定义的外部模块补类型信息，不能用来声明可被导入的运行时代码。TS能识别这个声明只是因为TS会自动扫描项目内的d.ts文件，不代表Webpack能找到对应的可执行代码。 #

对应解决方案 #

根据你实际的使用场景选对应方案即可，全程不需要修改CRA内置的Webpack配置：

场景1：仅需要声明全局类型/全局函数，不需要导入逻辑 #

这种情况不需要写任何import语句，按以下步骤调整：

• 将类型声明文件统一放在src目录下，命名建议为global.d.ts（你当前的tsconfig配置已经覆盖src下所有文件，不需要修改tsconfig.json）
• 去掉d.ts里的declare module包裹，直接声明全局类型/函数：

// src/global.d.ts
declare function someFunction(arg: number): void;

• 删除App.tsx里的import someFunction from 'myTypes'导入语句，直接在代码里调用someFunction()即可，TS会自动识别全局类型，Webpack也不会触发不存在的模块解析。
  如果你是要给已安装的、无自带类型的第三方npm包补类型，declare module '对应包名'的写法是正确的，但前提是这个包已经真实安装在node_modules中，Webpack能找到对应的运行时代码，d.ts仅补类型校验能力。

场景2：需要写可复用的工具函数/类型模块，在项目中导入使用 #

这种情况不要用.d.ts文件，直接写普通的TS文件即可：

• 新建src/myTypes.ts（注意后缀为.ts不是.d.ts），写入实际运行逻辑和类型：

// src/myTypes.ts
export default function someFunction(arg: number): void {
  // 写入函数实际执行逻辑
  console.log(arg);
}

• 因为你已经在tsconfig里配置了baseUrl: "src"，直接用import someFunction from 'myTypes'导入即可正常运行，TS会自动推导类型，Webpack也能找到对应的实体文件，不会报解析错误。

避坑提醒 #

• 项目内部的自定义代码不要用declare module 'xxx'的写法，这种环境模块声明仅用于描述外部存在、TS无法感知类型的代码，内部代码直接用普通.ts/.tsx文件编写，正常导出导入即可。
• CRA原生支持TS类型声明和路径别名解析，所有类似报错本质都是混淆了「类型声明文件」和「运行时代码文件」的边界，不需要eject或者修改Webpack配置就能解决。

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