如何用Wrangler/Miniflare本地开发Cloudflare Functions（文件路由）

用Wrangler本地调试 #

1. 确保Wrangler版本为最新
   先升级到最新版：npm install -g wrangler，旧版本可能不支持Pages Functions的基于文件路由本地运行。

2. 调整项目结构
   你的项目需要符合Cloudflare Pages的目录规范：

   你的项目根目录/
   ├── public/          # 存放静态资源（可选，没有可以创建空目录）
   ├── functions/       # 核心：存放基于文件的路由函数
   │   ├── api/
   │   │   └── test.ts  # 对应路由 /api/test
   │   └── [[path]].ts  # 可选兜底路由，处理未匹配的请求
   └── wrangler.toml    # Wrangler配置文件
   

3. 配置wrangler.toml
   不需要指定根Worker文件，配置文件要明确类型为pages，示例：

   name = "你的项目名称"
   type = "pages"
   account_id = "你的Cloudflare账号ID"
   project_name = "你的Pages项目名称"
   
   [build]
   command = ""  # 无需构建可留空
   publish = "public"
   
   [dev]
   port = 8788  # 本地运行端口，可自定义
   

4. 启动本地服务
   运行命令：wrangler pages dev，Wrangler会自动识别functions目录下的路由文件，无需指定根Worker，直接在本地模拟Cloudflare环境运行。

用Miniflare本地调试 #

1. 安装Miniflare
   项目内安装依赖：npm install -D miniflare

2. 配置运行脚本
   在项目的package.json中添加dev脚本：

   {
     "scripts": {
       "dev": "miniflare --pages --public public --functions functions"
     }
   }
   

   参数说明：

   • --pages：启用Pages模式
   • --public public：指定静态资源目录
   • --functions functions：指定路由函数目录

3. 启动本地服务
   运行npm run dev，Miniflare会加载functions目录下的所有路由文件，模拟Cloudflare Functions的运行环境。

关键注意事项 #

• 不要使用wrangler dev命令（这是针对单个Worker的调试命令），必须用wrangler pages dev来适配Pages的基于文件路由特性。
• 如果旧的wrangler.toml中有main字段，必须删除，否则会触发寻找根Worker文件的错误。

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