Next.js中next/script标签报错、脚本未引入问题排查

架构老林

2026-8-28

问题产生原因

Script组件放置位置不符合Pages Router渲染规则：当前代码把<Script>放在空Fragment<>的直接子级，和<Head>、<main>平级，在Next.js 12.x~13.x的Pages Router实现中，这种写法会导致Script组件的挂载逻辑找不到正确的DOM注入锚点，配合lazyOnload策略时会直接跳过脚本注入。
内联脚本缺少必填属性：如果直接在Script标签内编写内联JS代码而非通过src引入外部脚本，没有给Script组件设置唯一的id属性，会直接触发Next.js的组件校验报错，导致脚本无法渲染。
静态资源路径异常：没有提前确认/al.js路径的可访问性，可能存在文件未放在public根目录、文件名大小写不匹配、public目录静态资源配置被修改等问题，导致脚本请求返回404。
加载策略导致的误判：lazyOnload策略的触发时机是浏览器完全空闲时，如果页面调试阶段持续有资源加载、交互触发，脚本会被延迟很久才加载，容易被误以为没有引入。
组件属性冲突：给带src属性的Script组件同时编写内联脚本子内容，两种加载模式冲突会直接触发组件报错，导致脚本无法加载。

解决方案

按以下顺序排查即可：

校验静态资源路径有效性
启动项目后直接在浏览器访问http://localhost:你的项目端口/al.js，确认能正常返回al.js的文件内容。如果返回404，逐一检查：
- al.js是否直接放在项目public目录的根路径，没有嵌套在子文件夹中
- 文件名是否完全匹配，注意大小写（比如实际文件名为Al.js/al.JS在Linux部署环境会直接404）
- 没有修改Next.js默认的public目录静态资源映射规则
调整Script组件放置位置
Pages Router下不要把Script直接放在Fragment根层级平级放置，要么移到<Head>组件内部，要么移到页面的DOM容器（比如代码中的<main>标签）内部，参考修正后的外部脚本引入代码：

import React from 'react';
import Head from 'next/head';
import Script from 'next/script';

export default function Home(){
  return (
    <>
      <Head>
        <title>blog</title>
        <Script 
          src='/al.js'
          strategy='lazyOnload'
          onLoad={() => console.log('al.js加载完成')}
        />
      </Head>
      <main>
        页面业务内容
      </main>
    </>
  )
}

补全内联脚本必填属性
如果是在Script标签内直接写内联代码，必须给组件配置全局唯一的id属性，否则会直接报错，正确写法示例：

<Script id="track-log-script" strategy="afterInteractive">
  console.log('内联脚本执行，id属性是必填项')
</Script>

验证加载逻辑
如果调整位置后还是看不到脚本加载，临时把strategy='lazyOnload'替换为strategy='afterInteractive'测试，该策略会在页面完成hydration可交互后立即加载脚本，不会等待浏览器空闲，可以快速排除是lazyOnload延迟加载导致的误判。配合onLoad回调打印日志，就能明确知道脚本是否加载成功。
排查属性冲突
确认使用src引入外部脚本时，Script标签内部没有写任何内联JS代码，内联脚本和外部src属性二选一使用，同时存在会直接触发组件报错。

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