React(TypeScript)中使用NDEFReader报错“找不到名称”，如何解决？

我之前也踩过这个坑，Web NFC属于浏览器实验性API，TypeScript的标准类型库还没收录它的定义，再加上create-react-app的默认配置会严格做类型校验，所以才会抛出Cannot find name 'NDEFReader'的错误。下面是我亲测有效的解决步骤：

1. 添加自定义TypeScript类型声明 #

在项目的src目录下创建一个web-nfc.d.ts类型声明文件，手动告诉TypeScript这个API的结构：

interface NDEFReaderOptions {
  signal?: AbortSignal;
}

interface NDEFReadingEvent extends Event {
  message: NDEFMessage;
}

interface NDEFMessage {
  records: NDEFRecord[];
}

interface NDEFRecord {
  recordType: string;
  mediaType?: string;
  id?: string;
  data?: Uint8Array;
}

declare class NDEFReader extends EventTarget {
  constructor(options?: NDEFReaderOptions);
  scan(options?: NDEFReaderOptions): Promise<void>;
  write(message: NDEFMessage, options?: { signal?: AbortSignal }): Promise<void>;
  makeReadOnly(options?: { signal?: AbortSignal }): Promise<void>;
  onreading: ((this: NDEFReader, ev: NDEFReadingEvent) => any) | null;
  onreadingerror: ((this: NDEFReader, ev: Event) => any) | null;
}

declare global {
  interface Window {
    NDEFReader: typeof NDEFReader;
  }
}

export {};

这个文件会让TypeScript编译器识别NDEFReader及其相关的类型，消除类型报错。

2. 调整tsconfig.json配置 #

确认你的tsconfig.json包含以下关键配置（create-react-app生成的项目大多已经默认配置，重点检查lib字段）：

{
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "strict": true,
    // 其他默认配置...
  },
  "include": ["src"]
}

lib数组里的ESNext和DOM能保证TypeScript支持最新的DOM API相关类型。

3. 代码中增加运行时环境检测 #

Web NFC仅支持Chrome 81+移动端，所以在使用API前一定要做环境判断，避免在不支持的环境中崩溃：

if ('NDEFReader' in window) {
  // 这里写NFC扫描/写入逻辑
  const reader = new NDEFReader();
  
  reader.scan().then(() => {
    console.log("NFC扫描已启动");
    reader.onreading = (event) => {
      console.log("读取到NFC数据:", event.message.records);
    };
  }).catch(err => {
    console.error("扫描初始化失败:", err);
  });
} else {
  alert("当前浏览器不支持Web NFC功能，请使用移动端Chrome Beta测试");
}

关于webpack配置的说明 #

其实create-react-app默认的webpack配置已经允许使用实验性JS特性，你遇到的问题核心是类型缺失，而不是webpack的限制。只要补全类型声明，代码就能正常编译，不需要额外修改webpack配置。

最后别忘了在Chrome浏览器中开启chrome://flags/#enable-experimental-web-platform-features，并且在移动端Chrome Beta环境下测试功能。

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