Next.js TypeScript项目Cloudflare Pages Functions类型注解报错求助

问题原因 #

你的Next.js项目根目录默认的tsconfig.json没有适配Cloudflare Pages Functions的编译规则，且未排除functions目录，导致wrangler将functions下的TypeScript文件当做JavaScript直接解析，遇到类型注解语法就会抛出语法错误。Vite项目可以正常运行是因为其默认TS配置适配了worker侧的TS处理逻辑。

解决方案 #

按以下步骤配置即可解决：

• 第一步：安装Cloudflare Workers类型依赖
  在项目根目录执行安装命令：
  npm install @cloudflare/workers-types --save-dev

• 第二步：为functions目录单独创建TS配置
  在functions文件夹下新建tsconfig.json文件，内容如下：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "lib": ["ESNext"],
    "types": ["@cloudflare/workers-types"],
    "moduleResolution": "node",
    "noEmit": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["**/*.ts", "**/*.d.ts"]
}

你之前手动拷贝的PagesFunction类型可以删除，直接从该依赖包导入即可：
import type { PagesFunction } from "@cloudflare/workers-types"

• 第三步：调整根目录TS配置排除functions目录
  修改项目根目录的tsconfig.json，将functions目录加入exclude列表，避免Next.js前端编译流程处理该目录的代码：

{
  // 保留你原本的所有配置项不变，仅修改exclude字段
  "exclude": ["node_modules", "out", "functions"]
}

• 第四步：验证效果
  重新执行本地验证命令npx wrangler pages dev ./out，或者推送到Cloudflare Pages构建，类型注解报错就会消失，你可以正常使用PagesFunction类型、context参数类型注解以及env访问KV命名空间。

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