更新SPFx Yeoman生成器后WebPart.ts出现类型不兼容错误求助

问题原因 #

更新SPFx Yeoman生成器后，旧版@pnp/sp库的初始化方式（sp.setup({spfxContext: this.context})）出现类型不匹配，核心是新版SPFx调整了WebPartContext的结构，而旧版@pnp/sp的ISPFXContext类型定义未同步适配。

解决方案 #

步骤1：更新@pnp/sp到兼容版本 #

先确保@pnp/sp库版本与当前SPFx版本匹配，执行命令更新：

npm install @pnp/sp@latest @pnp/spfx-controls-react@latest --save

步骤2：修改初始化代码 #

新版@pnp/sp推荐使用SPFI实例结合SPFx适配器的方式初始化，替换原有的sp.setup代码：

import { spfi, SPFx } from "@pnp/sp";
// 根据业务需求引入所需的PnP模块
import "@pnp/sp/webs";
import "@pnp/sp/lists";

protected async onInit(): Promise<void> {
  await super.onInit();

  // 初始化SPFI实例，传入当前WebPart上下文
  const sp = spfi().using(SPFx(this.context));

  // 若需全局使用该实例，可挂载到类属性
  this._sp = sp;
}

// 类内定义对应属性
private _sp: ReturnType<typeof spfi>;

临时兼容方案（不推荐长期使用） #

如果暂时不想重构代码，可通过类型断言绕过类型检查：

protected onInit(): Promise<void> {
  sp.setup({
    spfxContext: this.context as unknown as ISPFXContext
  });
  return super.onInit();
}

说明 #

新版@pnp/sp采用实例化设计，更符合模块化规范，能避免全局状态的潜在问题。若使用全局sp对象，需确保在onInit中先执行await super.onInit()，保证上下文加载完成后再初始化。

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