2 min read

EmDash 博客部署到cloudflare实战教程

本教程基于实际操作路径，是最简化的部署流程。

🛠️ 准备工作

  • 一个 GitHub 账号
  • 一个 Cloudflare 账号
  • 本地安装 Node.js（推荐 v22+）和 npm

📝 部署步骤

第一步：在本地创建 EmDash 项目

bash

npm create emdash@latest

按交互提示选择：

  • Project name：blog-cloudflare（或自定义）
  • Where will you deploy：选择 Cloudflare Workers
  • Which template：选择 Blog
  • Package manager：选择 npm

如果安装依赖卡住（国内网络问题），按 Ctrl+C 终止，然后运行：

bash

npm install --registry=https://registry.npmmirror.com --legacy-peer-deps

第二步：升级关键依赖（⭐️ 最关键的一步）

在项目目录下运行这条命令，这是解决后续所有 ERESOLVE 构建报错的核心：

bash

npm install -D @cloudflare/workers-types@^5.20260828.1

这一步会将 @cloudflare/workers-types 从 v4 升级到 v5，与 wrangler 的版本要求保持一致，从而避免 npm ci 在云端构建时因 peer 依赖冲突而失败。

第三步：修改 wrangler.jsonc（免费账号必须）

打开项目根目录的 wrangler.jsonc 文件：

  1. 填入 D1 数据库 ID（需要在 Cloudflare 后台预先创建 D1 数据库，复制其 ID）
  2. 注释掉 worker_loaders 块（免费账号不支持 Dynamic Workers）

jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-emdash-site",
  "main": "./src/worker.ts",
  "compatibility_date": "2026-02-24",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-emdash-site",
      "database_id": "你的D1数据库ID"   // ← 替换为真实ID
    }
  ],
  "r2_buckets": [
    {
      "binding": "MEDIA",
      "bucket_name": "my-emdash-media"
    }
  ],
  // "worker_loaders": [ ... ],   // ← 免费账号务必注释或删除此块
  "triggers": {
    "crons": ["* * * * *", "*/2 * * * *"]
  }
}
提醒：D1 数据库和 R2 存储桶需要提前在 Cloudflare Dashboard 手动创建，wrangler 不会自动创建这些资源。

第四步：提交代码到 GitHub

bash

git init
git remote add origin https://github.com/你的用户名/你的仓库名.git
git add .
git commit -m "初始化 EmDash 博客"
git push -u origin main

第五步：在 Cloudflare Workers 中部署

方式一：使用 Cloudflare 自带的 Git 连接（你的成功路径）

  1. 登录 Cloudflare Dashboard → Workers 和 Pages → Workers → 创建应用程序 → 连接到 Git。
  2. 连接你的 GitHub 仓库。
  3. 在构建设置中，使用默认值即可（无需修改构建命令或部署命令）。
  4. 点击“保存并部署”。

方式二：使用 GitHub Actions（更可控，作为备选）

如果你想将部署流程完全托管在 GitHub，可以创建 .github/workflows/deploy.yml：

yaml

name: Deploy EmDash to Cloudflare Workers
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          wranglerVersion: '4.41.0'
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

然后在 GitHub 仓库的 Settings → Secrets 中添加 CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_API_TOKEN。

第六步：访问后台

部署成功后，访问：

text

https://你的项目名.你的用户名.workers.dev/_emdash/admin

按提示创建管理员账户，即可开始使用。

💡 核心要点总结

关键步骤

为什么必须做

升级 @cloudflare/workers-types

解决 wrangler v4+ 与 workers-types v4 的 peer 依赖冲突，避免 ERESOLVE 错误

注释 worker_loaders

免费账号不支持 Cloudflare Dynamic Workers，否则部署时会报错

创建 D1 数据库和 R2 存储桶

wrangler 不会自动创建这些资源，需要提前在 Dashboard 手动创建

提交 package-lock.json

确保云端 npm ci 能获取到完整的依赖锁定信息

🧩 常见问题

问题

解决方法

npm install 卡住

使用淘宝镜像：npm install --registry=https://registry.npmmirror.com --legacy-peer-deps

构建失败，提示 ERESOLVE

确认已执行 npm install -D @cloudflare/workers-types@^5.20260828.1 并提交

构建失败，提示 worker_loaders

确认 wrangler.jsonc 中的 worker_loaders 块已被注释

访问后台报错 401

确认 D1 数据库 ID 填写正确，数据库已创建

访问后台报错 500

检查 Cloudflare Dashboard 中 D1 数据库和 R2 存储桶的名称与 wrangler.jsonc 中的配置是否一致

我的成功经验证明：部署 EmDash 其实不需要复杂的配置，只需要做好关键的一步——升级依赖版本。 其他都交给 Cloudflare 的默认构建流程就可以了。感谢你的阅读！🎉

No comments yet

Continue reading