SPFx项目升级Node至v18.18.2后运行时Manifest文件加载报错求助

核心问题分析 #

SPFx项目升级到Node v18.18.2并适配SPFx 1.18.2后，构建工具链生成的manifest文件中testStrings.Paths会出现空对象{}，新版SPFx调试加载逻辑无法兼容这种空对象格式，触发类型错误。手动删除该字段可临时恢复正常，但每次serve/bundle时manifest会自动重新生成，问题反复出现。

具体解决步骤 #

1. 清理配置文件中的空Paths定义 #

• 检查项目根目录config/package-solution.json，若存在testStrings.Paths: {}配置，直接删除该字段或整个testStrings节点（无测试字符串需求时）。
• 遍历所有WebPart/Extension的src/**/manifest.json文件，移除所有testStrings.Paths为空对象的配置项。

2. 清除构建缓存并重新构建 #

执行命令彻底清理旧缓存，避免残留配置影响新构建：

gulp clean
gulp build

3. 对齐SPFx核心依赖版本 #

检查package.json中以下核心依赖是否统一为1.18.2版本：

• @microsoft/sp-build-web
• @microsoft/sp-module-interfaces
• @microsoft/sp-webpart-base
• @microsoft/sp-extension-base

若版本不一致，更新后重新安装依赖：

npm install

4. 自定义构建钩子自动清理空Paths字段 #

若上述步骤无效，修改gulpfile.js添加构建钩子，在manifest生成后自动移除空的testStrings.Paths：

const fs = require('fs');
const path = require('path');
const build = require('@microsoft/sp-build-web');

// 绑定到bundle完成后的钩子
build.hook('after:bundle:copy-assets', (ctx) => {
  const manifestsDir = path.join(ctx.outputPath, 'manifests');
  if (!fs.existsSync(manifestsDir)) return;

  fs.readdirSync(manifestsDir).forEach(fileName => {
    if (!fileName.endsWith('.json')) return;

    const manifestPath = path.join(manifestsDir, fileName);
    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

    // 删除空Paths字段，若testStrings为空则一并移除
    if (manifest.testStrings?.Paths && Object.keys(manifest.testStrings.Paths).length === 0) {
      delete manifest.testStrings.Paths;
      if (Object.keys(manifest.testStrings).length === 0) {
        delete manifest.testStrings;
      }
      fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
    }
  });
});

build.initialize(require('gulp'));

修改后重新执行gulp serve，构建工具会自动处理manifest文件。

5. 对比正常项目的配置差异 #

将问题项目与正常项目做以下对比排查：

• 对比package.json所有依赖版本，同步差异到问题项目。
• 检查两个项目的gulpfile.js自定义任务/钩子配置差异。
• 核对config目录下config.json、serve.json等配置文件的差异。

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