React TypeScript npm包添加本地字体遇模块找不到错误求助

问题分析 #

出现该错误的核心原因包括：导入路径使用不当、字体模块的TypeScript类型声明未正确生效、字体文件未被打包到发布目录中。

解决方案 #

1. 修正字体导入路径 #

fonts.tsx中使用了根目录绝对路径/src/assets/fonts/Poppins-Regular.ttf，TypeScript无法正确解析项目内的此类绝对路径，改为相对路径即可：

// src/assets/fonts/fonts.tsx
import { createGlobalStyle } from 'styled-components'
// 改为与字体文件同目录的相对路径
import Poppins_400 from './Poppins-Regular.ttf'

const FontStyles = createGlobalStyle`
    @font-face {
        font-family: "Poppins_400";
        src: local("Poppins_400"),
        url(${Poppins_400}) format("truetype");
        font-weight: 400;
    }
`
export default FontStyles

2. 确保TypeScript识别字体模块 #

如果已创建fonts.d.ts，检查以下两点：

• 类型声明文件内容需明确导出类型：

  // src/types/fonts.d.ts
  declare module '*.ttf' {
    const content: string;
    export default content;
  }
  

• 确认tsconfig.json的include字段包含该文件，现有配置"include": ["src", "src/types/*"]已满足要求，无需修改。

3. 打包时复制字体文件到发布目录 #

当前package.json的files仅包含dist，但TypeScript编译不会自动复制字体等资源文件，需手动添加复制步骤：

1. 安装copyfiles作为开发依赖：

   npm install --save-dev copyfiles
   

2. 修改package.json的scripts，在build后添加字体复制命令：

   {
     "scripts": {
       "build": "npm run build:esm && npm run build:cjs && npm run copy:fonts",
       "build:esm": "tsc",
       "build:cjs": "tsc --module commonjs --outDir dist/cjs",
       "copy:fonts": "copyfiles -u 2 src/assets/fonts/*.ttf dist/esm/assets/fonts && copyfiles -u 2 src/assets/fonts/*.ttf dist/cjs/assets/fonts",
       // 其他脚本保持不变
     }
   }
   

   解释：-u 2表示移除路径前两级（src/assets/fonts → assets/fonts），确保字体文件被复制到dist/esm和dist/cjs对应目录下，与编译后的代码路径匹配。

4. 验证配置 #

执行npm run build后，检查dist/esm/assets/fonts和dist/cjs/assets/fonts目录下是否存在字体文件，同时确认编译后的fonts.js中字体路径正确。

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