SvelteKit static adapter部署Cloudflare Pages失效及函数请求计数异常问题

异常1：static adapter部署后访问提示「No webpage was found for the web address」 #

核心原因 #

• adapter配置缺失：安装@sveltejs/adapter-static后未正确替换默认适配器、未开启全局预渲染，导致构建产物中缺失对应路由的HTML文件
• Cloudflare Pages构建输出路径配置错误，没有指向static adapter的默认输出目录
• 客户端路由场景未配置fallback，导致非根路径的客户端路由直接触发404

正确配置步骤 #

1. 安装静态适配器依赖

npm install -D @sveltejs/adapter-static

2. 修改项目根目录下的svelte.config.js配置

import adapter from '@sveltejs/adapter-static';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    adapter: adapter({
      pages: 'build',
      assets: 'build',
      // 纯静态全预渲染站点保持undefined即可；如果是纯客户端渲染的SPA项目填'index.html'
      fallback: undefined,
      precompress: true,
      strict: true
    }),
    // 全局开启全路由预渲染，无需在每个路由文件单独声明prerender规则
    prerender: {
      entries: ['*']
    }
  }
};

export default config;

3. Cloudflare Pages后台构建参数对齐配置

• 构建命令填：npm run build
• 构建输出目录填：build
• 如果是SPA项目需要客户端路由兜底，在Pages控制台的「Rules」配置中添加规则，将所有404请求重写到/index.html

异常2：使用cloudflare adapter时无自定义服务端函数，但Functions请求计数持续上涨 #

核心原因 #

这不是配置错误，是@sveltejs/adapter-cloudflare的默认运行机制导致的：该适配器会将SvelteKit的完整请求处理逻辑打包为单Worker文件部署到Cloudflare Pages Functions层，哪怕你没有编写任何自定义服务端逻辑（如+page.server.js/+server.ts文件），所有入站请求都会先经过这个Worker完成路由匹配、响应头注入、静态资源缓存规则处理等基础操作，因此所有请求都会被统计到Functions请求计数中。

优化方案 #

• 如果你的站点完全没有服务端渲染、服务端逻辑需求，直接按照上述static adapter的配置做全静态预渲染部署即可，构建产物全为静态文件，不会部署任何Functions逻辑，计数不会上涨，访问延迟也更低
• 如果确实需要使用cloudflare adapter（比如后续要加服务端逻辑、用Cloudflare Bindings等能力），可以在Pages控制台添加缓存规则，将/_app/immutable/*路径下的带哈希静态资源、图片/字体/静态脚本等资源路径设置为直接走CDN缓存、绕过Functions处理，这部分请求不会再被计入Functions统计，仅页面路由请求会经过Worker处理

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