如何为无TS定义的@salesforce/canvas-js-sdk编写类型定义文件？

我最近刚踩过这个坑！在React+TS项目里引入@salesforce/canvas-js-sdk时，确实会遇到类型报错+对象无法正常访问的双重问题——毕竟这个包官方没提供TypeScript定义，而且它的加载逻辑是直接往window对象上挂载Sfdc属性，不是常规的ES模块导出。

问题复盘 #

• 用import '@salesforce/canvas-js-sdk'时，VS Code会因为找不到类型定义报错
• 自己随便写的模块定义（比如declare module '@salesforce/canvas-js-sdk'）只能消掉编译红波浪，但运行时拿不到Sfdc对象
• 照着官方纯JS文档写的代码也跑不起来，必须用奇怪的方式才能拿到Sfdc引用

最终解决方案（无需修改原包） #

1. 简化但保留import语句

绝对不能省略import，因为它是触发包代码加载的关键，只要保留最基础的导入就行：

import '@salesforce/canvas-js-sdk';

这样打包工具（比如Webpack/Vite）会把这个包的代码注入到项目里，让它能在window上挂载Sfdc对象。

2. 编写全局类型声明文件

在你的项目源码目录下（比如src/）新建一个类型声明文件，比如salesforce-canvas.d.ts，内容如下：

declare global {
  interface Window {
    Sfdc: {
      // 这里可以根据官方文档补充你需要用到的属性/方法类型
      Canvas: {
        init: (config: any) => void;
        // 其他你用到的Canvas子方法，按需补充类型，暂时用any过渡也可以
      };
      // 其他Sfdc下的属性，比如Auth等，按需添加
    };
  }
}

// 这个export是必须的，让TypeScript识别这是一个模块
export {};

如果不想写太详细的类型，也可以先把Sfdc定义为any快速验证：

declare global {
  interface Window {
    Sfdc: any;
  }
}

export {};

3. 使用Sfdc对象

现在你就可以在组件里正常访问window.Sfdc了，而且TypeScript不会报错：

import '@salesforce/canvas-js-sdk';

function MyCanvasComponent() {
  const initCanvas = () => {
    window.Sfdc.Canvas.init({
      // 你的Canvas配置
    });
  };

  return <button onClick={initCanvas}>初始化Canvas</button>;
}

export default MyCanvasComponent;

为什么之前的方法不行？ #

• 只写模块声明declare module '@salesforce/canvas-js-sdk'，TypeScript只会认为这个模块存在，但不会关联到window上的Sfdc对象，所以运行时虽然包加载了，但TS不知道Sfdc的存在
• 省略import的话，包代码根本不会被打包工具引入，window上自然没有Sfdc对象

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