Nuxt 3生成SSG页面时引入本地脚本文件的最佳实践是什么？

所有方案默认接入Nuxt 3内置的资源优化链路，无需大规模修改旧脚本原有逻辑，即可在静态构建时自动获得资源压缩、hash缓存、按需加载、预加载提示等优化能力，按适配场景优先级排序如下：

优先级1：全站通用脚本 → public目录+全局useHead注入 #

• 将所有全站复用的旧JS文件放入项目public/js/目录，可完全保留旧站的文件路径结构，减少路径修改成本
• 在根目录app.vue中通过Nuxt内置的useHead方法统一注入，不要直接在模板写裸<script>标签：

<script setup lang="ts">
useHead({
  script: [
    // 非首屏核心脚本加defer属性，不阻塞页面初始渲染
    { src: '/js/old-global-utils.js', defer: true },
    // 必须在渲染前执行的核心依赖（如jQuery）可去掉defer，构建时会自动注入到页面合理位置
    { src: '/js/jquery.min.js' }
  ]
})
</script>

• 优化收益：SSG构建时会自动给资源路径拼接内容hash，避免静态托管时的缓存不生效问题，同时会给跨页复用的脚本自动添加prefetch/preload提示，提升加载速度。

优先级2：单路由/特定页面专属脚本 → 页面级useHead按需引入 #

• 仅在个别页面用到的脚本不要全局注册，直接在对应路由页面的script setup中调用useHead注入即可，例如仅商品详情页使用的旧图片放大插件：

<!-- pages/goods/[id].vue -->
<script setup lang="ts">
useHead({
  script: [
    // 非首屏脚本设置低加载优先级，不抢占核心资源带宽
    { src: '/js/old-image-zoom.js', defer: true, fetchpriority: 'low' }
  ]
})
</script>

• 优化收益：SSG构建时会自动做路由级资源拆分，用户访问对应页面时才会加载对应脚本，避免全局注入导致所有页面首屏体积膨胀。

优先级3：需自定义加载时机的脚本 → 内置useScript动态加载 #

• 对需要等DOM渲染完成、或用户触发特定交互才需要加载的脚本，使用Nuxt 3内置的useScript组合式函数加载，自带加载状态管理、重复加载拦截、SSG水合安全的能力：

// 示例：用户点击登录按钮时才加载旧版登录表单校验脚本
const handleLoginClick = async () => {
  const { loaded } = useScript('/js/old-login-validate.js', {
    trigger: 'manual' // 关闭自动加载
  })
  await loaded()
  // 脚本加载完成后再执行原有业务逻辑
  window.oldLoginValidate.init()
}

• 注意：不要手动用document.createElement('script')原生方式插入脚本，这类操作会绕过Nuxt的资源优化链路，SSG场景下还容易触发水合不匹配问题。

避坑说明 #

不要将旧的IIFE格式JS文件放入assets/目录走Vite模块化构建，这类旧脚本通常没有标准导出，被Vite打包后容易出现作用域错乱、全局变量丢失的问题；放入public目录可保留脚本原有的执行逻辑，同时不影响Nuxt对静态资源的优化处理。
如果旧脚本之间有严格的加载顺序依赖，只需在useHead的script配置数组中按依赖顺序排列即可，Nuxt会严格按照配置顺序注入标签，不会打乱原有依赖关系。
不要直接在Vue组件模板中硬编码<script src="/js/xxx.js">标签，这类标签不会被Nuxt资源处理器识别，无法自动添加缓存hash、预加载提示，还可能在客户端水合时出现重复加载问题。

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