在NextJS（TypeScript）中引入外部Script函数的实现问题

1. 使用Next.js官方的next/script组件加载脚本 #

Next.js提供了专门的Script组件来管控外部脚本的加载时机，能避免原生<script>标签在SSR/SSG阶段的加载顺序问题：

// 在_app.tsx或具体的page.tsx中引入
import Script from 'next/script';

export default function MyApp({ Component, pageProps }) {
  return (
    <>
      {/* 根据需求选择加载策略，beforeInteractive确保在页面交互前完成加载 */}
      <Script
        src="https://api.site.com/js/v1/script.js"
        strategy="beforeInteractive"
        onLoad={() => {
          console.log('外部脚本加载完成');
        }}
      />
      <Component {...pageProps} />
    </>
  );
}

2. 为全局变量添加TypeScript类型声明 #

TypeScript无法识别未声明的全局变量，需创建类型声明文件来消除类型报错：

在项目根目录或src目录下新建global.d.ts文件，内容如下：

declare global {
  interface Window {
    ScriptJS: () => {
      execute: (input: Record<string, any>) => any;
      // 可根据实际函数功能补充更多类型定义
    };
  }
}

export {};

3. 安全调用全局函数 #

必须确保脚本加载完成后再调用函数，避免ReferenceError：

方法一：在Script组件的onLoad回调中调用 #

<Script
  src="https://api.site.com/js/v1/script.js"
  strategy="beforeInteractive"
  onLoad={() => {
    const fn = window.ScriptJS();
    const someOutput = fn.execute({ key: 'your-input-value' });
    // 处理函数返回结果
  }}
/>

方法二：在组件中通过useEffect判断加载状态 #

import { useEffect } from 'react';

export default function MyPage() {
  useEffect(() => {
    if (typeof window.ScriptJS === 'function') {
      const fn = window.ScriptJS();
      const someOutput = fn.execute({ key: 'your-input-value' });
      // 处理结果
    } else {
      console.error('外部脚本未加载完成');
    }
  }, []);

  return <div>页面内容</div>;
}

错误原因说明 #

• 直接用原生<script>标签：Next.js的SSR/SSG阶段会在服务器端渲染，此时window对象不存在，脚本还未在客户端加载完成就执行代码，导致ReferenceError。
• 使用require()/import()：外部脚本是全局变量形式而非ES模块，动态导入语法不适用这类脚本，需通过全局变量访问。

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