fix(proxy): disable proxying for static deployments (1.x backport) (#877)

Author: harlan-zw

docs/content/docs/1.guides/2.first-party.md

@@ -236,23 +236,11 @@ PostHog receives the proxy endpoint through SDK config, so it can proxy collecti
 
 ### Static Hosting (SSG)
 
-The reverse proxy requires a **server runtime**. A fully static deployment serves the output of [`nuxt generate`](https://nuxt.com/docs/getting-started/prerendering) without a Nitro process to handle `/_scripts/p/**`. Nuxt Scripts warns for known static presets, but it does not rewrite proxy URLs to their third-party origins. Disable proxying for affected scripts or use a host that supports external-origin rewrites. For example, [Vercel rewrites](https://vercel.com/docs/routing/rewrites) accept `/:path*` captures and external destinations:
-
-```json [vercel.json]
-{
-"rewrites": [
- { "source": "/_scripts/p/www.google-analytics.com/:path*", "destination": "https://www.google-analytics.com/:path*" },
- { "source": "/_scripts/p/www.googletagmanager.com/:path*", "destination": "https://www.googletagmanager.com/:path*" },
- { "source": "/_scripts/p/connect.facebook.net/:path*", "destination": "https://connect.facebook.net/:path*" }
- ]
-}
-```
+The reverse proxy requires a **server runtime**. A fully static deployment serves the output of [`nuxt generate`](https://nuxt.com/docs/getting-started/prerendering) without a Nitro process to handle `/_scripts/p/**`.
 
-[Netlify proxy rewrites](https://docs.netlify.com/manage/routing/redirects/rewrites-proxies/) use a `200` rule such as `/_scripts/p/www.google-analytics.com/* https://www.google-analytics.com/:splat 200`. Cloudflare Pages is different: its [`_redirects` proxy rules](https://developers.cloudflare.com/pages/configuration/redirects/#proxying) support only relative destinations, not external domains. Use a [Pages Function](https://developers.cloudflare.com/pages/functions/) or Worker if you need this proxy on a static Cloudflare Pages deployment. Only configure domains your site uses; Nuxt DevTools → Scripts and Nitro logs show the registered set.
+Nuxt Scripts detects static output (`nuxt generate`, `nuxt build --prerender`, or a static Nitro preset) and disables proxying automatically, with a build warning listing the affected scripts. Scripts still bundle and load from your domain, but their collection requests keep their original third-party URLs and go directly to their origins. Proxy privacy and anonymization do not apply to those direct requests.
 
-::callout{type="warning"}
-Platform-level rewrites bypass the privacy anonymization layer. The proxy handler only runs in a Nitro server runtime.
-::
+To keep requests proxied and anonymized, deploy the server output of `nuxt build` to a host that runs Nitro.
 
 ## Proxy Endpoint Security
 
@@ -387,7 +375,7 @@ The module injects a per-request page token into the SSR payload, so the respons
 
 URL signing requires a server runtime to verify HMAC signatures. Two deployment modes cannot support signing:
 
-**`nuxt generate` (SSG) with static hosting**: Prerendered pages contain proxy URLs, but no Nitro server exists at runtime to verify signatures or forward requests. Proxy endpoints will not work on static hosts such as GitHub Pages. If you need proxy endpoints alongside prerendered pages, deploy to a server target that supports runtime request handling; [Vercel supports both static and server-rendered Nuxt deployments](https://vercel.com/docs/frameworks/full-stack/nuxt).
+**`nuxt generate` (SSG) with static hosting**: Static output has no proxy route and no proxy URLs; scripts send their requests directly to their third-party origins. No Nitro server exists at runtime to verify signatures or forward requests. If you need proxy endpoints alongside prerendered pages, deploy to a server target that supports runtime request handling; [Vercel supports both static and server-rendered Nuxt deployments](https://vercel.com/docs/frameworks/full-stack/nuxt).
 
 **`ssr: false` (SPA mode)**: No server-side rendering means no opportunity to sign URLs or embed page tokens. The signing secret lives in server-only runtime config and cannot be accessed from the client. Proxy endpoints still function if deployed with a server, but requests will be unsigned.
 
@@ -550,7 +538,7 @@ Routing a request through your domain does not settle the consent question. For
 | Problem | Fix |
 |---------|-----|
 | Analytics not tracking | Check DevTools → Network for `/_scripts/p/` requests. Check Nitro server logs for proxy errors |
-| Proxy not working on static site | Static hosts do not run the Nitro proxy handler. Disable proxying, add platform rewrites, or switch to a server deployment. See [Static Hosting](#static-hosting-ssg)|
+| Proxy not working on static site | Static output disables the proxy automatically and collection requests go direct. Deploy the `nuxt build` server output to enable proxying. See [Static Hosting](#static-hosting-ssg)|
 | Stale script | Remove `node_modules/.cache/nuxt/scripts` and rebuild |
 | Build download fails | Set `assets.fallbackOnSrcOnBundleFail: true`{lang="ts"} to fall back to direct loading |
 | Debugging | Open Nuxt DevTools → Scripts to see proxy routes and privacy status |

packages/script/src/module.ts

@@ -288,6 +288,42 @@ export function isProxyDisabled(
 returnfalse
 }
 
+/**
+ * Nitro presets with no server runtime: `/_scripts/p/**` cannot be served, so
+ * proxy URLs written into bundled scripts would 404/405 in production.
+ * Nitro accepts each name in hyphen, underscore, and camelCase form.
+ */
+exportconstSTATIC_PROXY_PRESETS=[
+'static',
+'github-pages',
+'gitlab-pages',
+'cloudflare-pages-static',
+'netlify-static',
+'vercel-static',
+'zeabur-static',
+'zerops-static',
+]
+
+/**
+ * Normalize a preset id the way Nitro resolves it: camelCase and underscore
+ * spellings (`githubPages`, `github_pages`) map to the hyphen form (`github-pages`).
+ */
+exportfunctionnormalizeNitroPreset(preset: string): string{
+returnpreset.replace(/[A-Z]/g,m=>`-${m.toLowerCase()}`).replace(/_/g,'-')
+}
+
+/**
+ * Whether the build targets static output with no Nitro server runtime.
+ * `nuxi generate` and `nuxt build --prerender` set `_generate` and `nitro.static`
+ * through CLI overrides; static presets arrive via `nitro.preset`, `NITRO_PRESET`,
+ * or `SERVER_PRESET` in any of Nitro's accepted spellings.
+ */
+exportfunctionisStaticProxyTarget(options: {generate?: boolean,nitroStatic?: boolean,preset?: string}): boolean{
+return!!options.generate
+||options.nitroStatic===true
+||STATIC_PROXY_PRESETS.includes(normalizeNitroPreset(options.preset||''))
+}
+
 exportfunctionapplyAutoInject(
 registry: NuxtConfigScriptRegistry,
 runtimeConfig: Record<string,any>,
@@ -740,15 +776,26 @@ export default defineNuxtModule<ModuleOptions>({
 __NUXT_SCRIPTS_UNHEAD_SOURCELESS__: unheadSourceLessConst,
 }
 
-// Register proxy handler unconditionally. The handler rejects unknown domains
-// at runtime, so it's safe to register even when no scripts use proxy.
+// Register the proxy handler for server targets. The handler rejects unknown
+// domains at runtime, so it's safe to register even when no scripts use proxy.
 constscriptsBase=config.prefix||'/_scripts'
 constproxyPrefix=`${scriptsBase}/p`
 constassetsPrefix=`${scriptsBase}/assets`
 constproxyConfigs: Partial<Record<RegistryScriptKey,ProxyConfig>>={}
 
 constproxyHandlerPath=awaitresolvePath('./runtime/server/proxy-handler')
-addServerHandler({route: `${proxyPrefix}/**`,handler: proxyHandlerPath})
+// Static targets (nuxi generate, static presets) have no server runtime to
+// serve the proxy: skip the route so the proxy is fully opt-in for them.
+conststaticProxyTarget=isStaticProxyTarget({
+// `_generate` arrives untyped through the nuxi generate CLI override. Nitro's
+// preset option already merges CLI args, env, and nuxt.config by module setup.
+generate: (nuxt.optionsas{_generate?: boolean})._generate,
+nitroStatic: (nuxt.options.nitroasany)?.static,
+preset: (nuxt.options.nitroasany)?.preset||process.env.NITRO_PRESET||process.env.SERVER_PRESET,
+})
+if(!staticProxyTarget){
+addServerHandler({route: `${proxyPrefix}/**`,handler: proxyHandlerPath})
+}
 
 // In dev, sink Vercel Analytics insight POSTs to `/_vercel/insights/*` so
 // they don't 404. Vercel's edge serves this path in production; locally
@@ -960,6 +1007,7 @@ export default defineNuxtModule<ModuleOptions>({
 constpartytownScripts=newSet<string>()
 
 letanyNeedsProxy=false
+constproxyConfiguredKeys: string[]=[]
 constregistryKeys=Object.keys(config.registry||{})
 for(constkeyofregistryKeys){
 constscript=scriptByKey.get(key)
@@ -975,8 +1023,10 @@ export default defineNuxtModule<ModuleOptions>({
 
 constresolved=resolveCapabilities(script,mergedOverrides)
 
-if(resolved.proxy)
+if(resolved.proxy){
 anyNeedsProxy=true
+proxyConfiguredKeys.push(key)
+}
 
 if(resolved.partytown){
 partytownScripts.add(key)
@@ -999,8 +1049,12 @@ export default defineNuxtModule<ModuleOptions>({
 constproxyAlias=config.proxy?.alias
 letdomainAliases: Record<string,string>={}
 
-// Finalize proxy setup: build configs, register intercept plugin, wire devtools
-if(anyNeedsProxy){
+// Finalize proxy setup: build configs, register intercept plugin, wire devtools.
+// Static targets (nuxi generate, static presets) have no server runtime to
+// serve `/_scripts/p/**`: skip every proxy integration (AST rewrites, intercept
+// plugin, auto-injected endpoints, URL signing) so collection requests keep
+// their original third-party URLs and work on static hosting.
+if(anyNeedsProxy&&!staticProxyTarget){
 constbuiltConfigs=buildProxyConfigsFromRegistry(registryScripts,scriptByKey)
 Object.assign(proxyConfigs,builtConfigs)
 
@@ -1108,17 +1162,6 @@ export default defineNuxtModule<ModuleOptions>({
 logger.success(`Proxy mode enabled for ${registryKeys.length} script(s), ${totalDomains} domain(s) proxied (privacy: ${privacyLabel})`)
 }
 
-// Warn for static presets
-constproxyStaticPresets=['static','github-pages','cloudflare-pages-static','netlify-static','azure-static','firebase-static']
-constproxyPreset=process.env.NITRO_PRESET||''
-if(proxyStaticPresets.includes(proxyPreset)){
-logger.warn(
-`Proxy collection endpoints require a server runtime (detected: ${proxyPreset||'static'}).\n`
-+'Scripts will be bundled, but collection requests will not be proxied and URL signing will be unavailable.\n'
-+'Options: configure platform rewrites, switch to server-rendered mode, or disable with proxy: false.',
-)
-}
-
 // Expose devtools data
 if(nuxt.options.dev){
 nuxt.options.runtimeConfig.public['nuxt-scripts-devtools']=buildDevtoolsData(proxyPrefix,privacyLabel,devtoolsScripts,aliasToDomain)asany
@@ -1137,6 +1180,13 @@ export default defineNuxtModule<ModuleOptions>({
 }
 }
 }
+elseif(anyNeedsProxy){
+logger.warn(
+`[nuxt-scripts] Static output detected (nuxi generate or a static Nitro preset); the scripts proxy requires a server runtime.\n`
++`Proxying, its privacy anonymization, and proxy URL signing are disabled for: ${proxyConfiguredKeys.join(', ')}. Scripts still bundle, and their requests go directly to their third-party origins.\n`
++`Deploy the Nuxt server output (nuxt build) to enable proxying.`,
+)
+}
 
 constmoduleInstallPromises: Map<string,()=>Promise<boolean>|undefined>=newMap()
 
@@ -1227,10 +1277,7 @@ export default defineNuxtModule<ModuleOptions>({
 )asany
 
 // Signing requires a server runtime to verify HMACs. Skip setup entirely
-// for SPA mode or static presets where no Nitro server exists at runtime.
-conststaticPresets=['static','github-pages','cloudflare-pages-static','netlify-static','azure-static','firebase-static']
-constnitroPreset=process.env.NITRO_PRESET||''
-constisStaticTarget=staticPresets.includes(nitroPreset)
+// for SPA mode or static output where no Nitro server exists at runtime.
 constisSpa=nuxt.options.ssr===false
 
 // Proxy security explicitly disabled: skip secret resolution and the page
@@ -1240,11 +1287,11 @@ export default defineNuxtModule<ModuleOptions>({
 logger.info('[security] Proxy security disabled via `security: false`. Proxy endpoints will pass requests through without signature verification.')
 }
 }
-elseif(anyHandlerRequiresSigning&&(isSpa||isStaticTarget)){
+elseif(anyHandlerRequiresSigning&&(isSpa||staticProxyTarget)){
 logger.warn(
-`[security] URL signing requires a server runtime${isStaticTarget ? ` (detected preset: ${nitroPreset})` : ' (ssr: false)'}.\n`
-+' Proxy endpoints will work without signature verification.\n'
-+' To enable signing, deploy with a server-rendered target or configure platform-level rewrites.',
+`[security] URL signing requires a server runtime${staticProxyTarget ? ' (static output)' : ' (ssr: false)'}.`
++'\n Proxy endpoints will work without signature verification.'
++'\n To enable signing, deploy with a server-rendered target or configure platform-level rewrites.',
 )
 }
 // Resolve the HMAC signing secret only when at least one handler needs it

test/unit/static-proxy-target.test.ts

@@ -0,0 +1,46 @@
+import{describe,expect,it}from'vitest'
+import{isStaticProxyTarget,normalizeNitroPreset,STATIC_PROXY_PRESETS}from'../../packages/script/src/module'
+
+describe('isStaticProxyTarget',()=>{
+it('is false for a regular server build',()=>{
+expect(isStaticProxyTarget({generate: false,nitroStatic: false,preset: 'cloudflare_pages'})).toBe(false)
+expect(isStaticProxyTarget({})).toBe(false)
+expect(isStaticProxyTarget({preset: 'vercel'})).toBe(false)
+expect(isStaticProxyTarget({preset: 'netlify'})).toBe(false)
+})
+
+it('detects nuxi generate via _generate and nitro.static',()=>{
+expect(isStaticProxyTarget({generate: true})).toBe(true)
+expect(isStaticProxyTarget({generate: true,preset: 'cloudflare'})).toBe(true)
+expect(isStaticProxyTarget({nitroStatic: true})).toBe(true)
+})
+
+it('detects every static preset in its hyphen, underscore, and camelCase form',()=>{
+expect(isStaticProxyTarget({preset: 'static'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'github_pages'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'githubPages'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'gitlab_pages'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'cloudflare_pages_static'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'cloudflarePagesStatic'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'netlify_static'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'vercel_static'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'zeabur_static'})).toBe(true)
+expect(isStaticProxyTarget({preset: 'zerops_static'})).toBe(true)
+})
+
+it('keeps the preset list free of non-static or unknown presets',()=>{
+// azure-static and firebase-static are not Nitro presets; gitlab-pages is.
+expect(STATIC_PROXY_PRESETS).not.toContain('azure-static')
+expect(STATIC_PROXY_PRESETS).not.toContain('firebase-static')
+expect(STATIC_PROXY_PRESETS).toContain('gitlab-pages')
+})
+})
+
+describe('normalizeNitroPreset',()=>{
+it('maps underscore and camelCase spellings onto the hyphen form',()=>{
+expect(normalizeNitroPreset('github_pages')).toBe('github-pages')
+expect(normalizeNitroPreset('githubPages')).toBe('github-pages')
+expect(normalizeNitroPreset('github-pages')).toBe('github-pages')
+expect(normalizeNitroPreset('static')).toBe('static')
+})
+})