在React中使用IBM Carbon Design System时控制台出现字体错误

问题根源 #

你遇到的Failed to decode downloaded font和OTS parsing error: invalid sfntVersion，本质是Vite没正确解析Carbon包内字体文件的路径——加载到的不是有效字体资源（大概率是404页面），因此触发字体解码失败。

修复步骤 #

1. 配置Vite的字体路径解析 #

修改项目根目录的vite.config.ts，加入以下配置：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  css: {
    preprocessorOptions: {
      scss: {
        // 覆盖Carbon的字体路径变量，让Vite定位到正确的字体文件位置
        additionalData: `@use "@carbon/react/scss/config" with (
          $font-path: "/node_modules/@carbon/react/assets/fonts"
        );`,
      },
    },
  },
  // 告诉Vite识别woff/woff2格式的字体资源
  assetsInclude: ['**/*.woff', '**/*.woff2'],
});

2. 调整SCSS导入（可选） #

如果不想在Vite配置里全局注入，也可以在每个SCSS文件开头先配置路径，再引入Carbon：

@use "@carbon/react/scss/config" with (
  $font-path: "/node_modules/@carbon/react/assets/fonts"
);
@use "@carbon/react";

3. 重启开发服务器 #

修改配置后必须重启Vite开发服务器，确保新配置生效。

额外检查项 #

• 确认@carbon/react和sass版本匹配，Carbon对sass版本有明确要求，可查看对应版本的官方文档依赖说明
• 排查项目中是否有自定义路径别名或其他CSS插件，可能干扰了字体路径的解析

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