v1 迁移指南
从 v0.x 升级到 v1.0 的迁移指南。
v1 新特性
v1 着重于隐私和性能——通过您自己的域名路由分析，脚本移出主线程，并在服务器端渲染社交嵌入内容。
第一方模式
通过您自己的域名路由所有脚本流量，以保障隐私和广告拦截器兼容性。
export default defineNuxtConfig({
scripts: {
firstParty: true,
registry: {
googleAnalytics: { id: 'G-XXXXXX' },
metaPixel: { id: '123456' },
}
}
})
- 用户 IP 保持私密 — 第三方只看到您服务器的 IP
- 无第三方 Cookie — 请求是同源的
- 兼容广告拦截器 — 请求表现为第一方
支持：Google Analytics、GTM、Meta Pixel、TikTok、Segment、Clarity、Hotjar、X/Twitter、Snapchat、Reddit。
Partytown 支持
利用 web workers 将脚本从主线程加载。
export default defineNuxtConfig({
modules: ['@nuxtjs/partytown', '@nuxt/scripts'],
scripts: {
partytown: ['plausible', 'fathom', 'umami'],
registry: {
plausible: { domain: 'example.com' }
}
}
})
转发数组对支持的脚本会自动配置。
GA4 在 Partytown 中存在已知问题。GTM 不兼容。建议使用 Plausible、Fathom 或 Umami。
SSR 社交嵌入
服务器端渲染 X（原 Twitter）和 Instagram 嵌入，无需加载第三方 JavaScript。
<ScriptXEmbed tweet-id="1754336034228171055">
<template #default="{ userName, text, likesFormatted }">
<!-- 通过作用域插槽完全控制样式 -->
</template>
</ScriptXEmbed>
<ScriptInstagramEmbed post-url="https://instagram.com/p/ABC123/">
<template #default="{ html }">
<div v-html="html" />
</template>
</ScriptInstagramEmbed>
- 零第三方 JavaScript
- X/Instagram 不会设置 Cookie
- 不共享用户 IP
- 所有内容均从您的域名提供
脚本重载
SPA 导航后重新执行 DOM 扫描脚本：
const script = useScript('/third-party.js')
await script.reload()
SRI 完整性哈希
export default defineNuxtConfig({
scripts: {
assets: {
integrity: 'sha384' // 或 'sha256'、'sha512'
}
}
})
GTM 默认同意
export default defineNuxtConfig({
scripts: {
registry: {
googleTagManager: {
id: 'GTM-XXXX',
defaultConsent: {
ad_storage: 'denied',
analytics_storage: 'denied'
}
}
}
}
})
新增注册脚本
- PostHog — 产品分析及功能开关
- Google reCAPTCHA v3 — 隐形机器人防护
- TikTok Pixel — 转化跟踪
- Google Sign-In — 一键登录认证
Google 地图配色模式
<ScriptGoogleMaps
:map-ids="{ light: 'LIGHT_MAP_ID', dark: 'DARK_MAP_ID' }"
/>
自动根据 @nuxtjs/color-mode 或手动 color-mode 属性切换。
重大变更
YouTube 播放器
宽高比
使用 ratio 属性替代从 width/height 推导：
<ScriptYouTubePlayer
video-id="..."
- :width="1280"
- :height="720"
+ ratio="16/9"
/>
默认是 16/9。
占位图像
默认的 object-fit 从 contain 改为 cover：
<ScriptYouTubePlayer video-id="..." placeholder-object-fit="contain" />
多播放器
现在播放器实例已正确隔离。请移除任何针对多播放器的解决方案。
Google Tag Manager
onBeforeGtmStart 回调
现会在缓存/预初始化脚本时触发。需防止多次调用：
let initialized = false
useScriptGoogleTagManager({
onBeforeGtmStart: (gtag) => {
if (initialized) return
initialized = true
// 你的初始化代码
}
})
类型增强
模板结构已重新组织。升级后请执行 nuxi prepare。