Next.js 15.0.2创建Stockfish Web Worker遇TP1001 TypeScript错误求助

我用Turbopack搭建Next.js 15.0.2 + TypeScript项目，集成Stockfish国际象棋引擎，在客户端通过Web Worker加载public文件夹里的Stockfish库，代码如下：

const stockfishPath = '/stockfish/stockfish-nnue-16-single.js';

const createStockfishWorker = () => {
  try {
    const worker = new Worker(stockfishPath);
    return worker;
  } catch (error) {
    throw Error(`Initialize stockfish worker failed: ${error}`);
  }
};

export default createStockfishWorker;

功能完全正常，但控制台出现错误提示：

GET /analysis/w 200 in 2089ms
⚠ ./src/services/stockfish/createStockfishWorker.ts:7:20
error TP1001 new Worker("/stockfish/stockfish-nnue-16-single.js") is not statically analysable
   5 | const createStockfishWorker = () => {
   6 |   try {
>  7 |     const worker = new Worker(stockfishPath);
     |                    ^^^^^^^^^^^^^^^^^^^^^^^^^
   8 |     postMessage(['uci'], worker);
   9 |     return worker;
  10 |   } catch (error) {

已尝试的操作：

• Web Worker动态创建功能正常，无功能问题
• 确认TP1001是Turbopack提示的Worker路径无法静态分析的错误
• 使用// @ts-ignore无法抑制该错误

环境信息：

• Next.js版本：15.0.2
• TypeScript版本：^5
• Stockfish库从public文件夹提供服务

需要解决的问题：

1. 为何Worker功能正常却出现该错误？
2. 如何有效解决或抑制该错误？
3. Next.js + TypeScript中是否有更优的动态加载Worker方式可避免该错误？

1. 错误原因 #

这个TP1001错误不是TypeScript原生报错，而是Turbopack的静态分析检查结果。Turbopack作为Next.js 15默认的构建工具，会尝试静态分析所有资源引用，包括Worker路径。你用变量stockfishPath传入new Worker()，Turbopack无法在构建时确定这个变量的具体值，所以抛出警告级错误。但实际运行时浏览器能正确解析public文件夹下的路径，因此功能不受影响。

另外// @ts-ignore无效，是因为这不是TypeScript的类型错误，而是Turbopack的构建检查错误，TypeScript的忽略注释管不到构建工具的提示。

2. 解决/抑制错误的方法 #

方法一：直接传入路径字面量 #

把路径直接写在new Worker()里，让Turbopack能静态识别路径：

const createStockfishWorker = () => {
  try {
    const worker = new Worker('/stockfish/stockfish-nnue-16-single.js');
    return worker;
  } catch (error) {
    throw Error(`Initialize stockfish worker failed: ${error}`);
  }
};

这是最直接的解决方式，Turbopack能静态分析到路径，错误会直接消失。

方法二：用环境变量管理路径 #

如果必须用变量管理路径，可以用process.env.NEXT_PUBLIC_前缀的环境变量，Turbopack会识别这类环境变量为静态可分析的资源路径：

1. 在.env.local中添加：

NEXT_PUBLIC_STOCKFISH_PATH='/stockfish/stockfish-nnue-16-single.js'

2. 在代码中使用：

const stockfishPath = process.env.NEXT_PUBLIC_STOCKFISH_PATH!;

const createStockfishWorker = () => {
  try {
    const worker = new Worker(stockfishPath);
    return worker;
  } catch (error) {
    throw Error(`Initialize stockfish worker failed: ${error}`);
  }
};

方法三：关闭Turbopack的Worker静态检查（不推荐） #

在next.config.ts里添加配置，关闭Turbopack的Worker静态分析规则：

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      'worker': {
        staticAnalysis: false,
      },
    },
  },
};

export default nextConfig;

这个方法不推荐，会丢失Turbopack对Worker资源的优化能力，比如缓存、打包处理等。

3. Next.js + TypeScript中更优的Worker加载方式 #

Next.js官方推荐用Worker文件导入的方式，而非直接引用public文件夹的脚本，这样能让构建工具自动处理Worker的打包、类型检查和资源优化：

步骤1：迁移Stockfish脚本到src目录 #

将stockfish-nnue-16-single.js移到src/workers/目录下，同时创建对应的类型声明文件（可选但推荐）：

// src/workers/stockfish.d.ts
declare module '*.js' {
  const WorkerFactory: new () => Worker;
  export default WorkerFactory;
}

步骤2：导入并创建Worker #

// createStockfishWorker.ts
import StockfishWorker from '../workers/stockfish-nnue-16-single.js';

const createStockfishWorker = () => {
  try {
    const worker = new StockfishWorker();
    return worker;
  } catch (error) {
    throw Error(`Initialize stockfish worker failed: ${error}`);
  }
};

export default createStockfishWorker;

如果需要懒加载，可以用动态导入：

const createStockfishWorker = async () => {
  try {
    const { default: StockfishWorker } = await import('../workers/stockfish-nnue-16-single.js');
    const worker = new StockfishWorker();
    return worker;
  } catch (error) {
    throw Error(`Initialize stockfish worker failed: ${error}`);
  }
};

export default createStockfishWorker;

这种方式的优势：

• Turbopack自动处理Worker的打包、代码分割和缓存
• 获得TypeScript的类型支持
• 彻底避免静态分析错误，同时享受构建工具的优化

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