Cloudflare Cli 入门指南

一、安装与认证

安装 Wrangler

# 推荐使用 npm/yarn/pnpm（避免全局安装）
# 推荐局部安装（避免全局依赖冲突）
npm install -D wrangler@latest  # npm
yarn add -D wrangler@latest     # Yarn
pnpm add -D wrangler@latest     # pnpm

• 验证安装：npx wrangler --version

登录认证

wrangler login

• 自动打开浏览器完成 OAuth 授权

• 权限控制：--scopes-list=workers,pages,d1 可限制 CLI 权限范围

二、Worker 项目配置 (使用 Vite)

初始化项目

wrangler my-worker
cd my-worker
npm install -D @cloudflare/workers-types vite @cloudflare/vite-plugin

目录结构

my-worker/
├── dist/                # Vite 构建输出
├── src/
│   ├── index.ts         # Worker 入口
│   └── utils/           # 工具函数
├── vite.config.ts       # Vite 配置
└── wrangler.toml       # 核心配置

关键配置（wrangler.toml）

• 静态资源绑定：[site] 配置正确，但需强调 bucket 路径需与 Vite 的 build.outDir 一致。

• KV 命名空间：id 需通过 wrangler kv:namespace create 获取，示例中的 xxxxxx 需替换为实际值 

• D1 数据库：database_id 同样需替换为真实 ID，可通过 wrangler d1 list 查询

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2025-06-17"

# 静态资源绑定（需与 Vite 的 outDir 一致）
[site]
bucket = "./dist"
entry-point = "src"

# 全局变量（生产/测试环境共用）
[vars]
LOG_LEVEL = "info"

# KV 命名空间（需先创建）
kv_namespaces = [
  { binding = "CACHE", id = "your-kv-id" }  # 通过 `wrangler kv:namespace create` 获取
]

# D1 数据库（无环境区分）
[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "your-db-id"  # 通过 `wrangler d1 list` 查询

Worker 脚本示例（src/index.ts）

interface Env {
  ASSETS: Fetcher;
  CACHE: KVNamespace;
  DB: D1Database;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname === '/' ? '/index.html' : url.pathname;

    try {
      // 1. 优先从 KV 缓存获取
      const cached = await env.CACHE.get(path);
      if (cached) return new Response(cached);

      // 2. 回源到 dist 目录（含错误重试）
      const response = await env.ASSETS.fetch(request).catch(() => null);
      if (!response) return new Response("Backend Error", { status: 502 });

      if (response.status === 200) {
        // 缓存新文件（TTL 24h）
        await env.CACHE.put(path, await response.clone().text(), {
          expirationTtl: 86400,
        });
        return response;
      }
      return new Response("Not Found", { status: 404 });
    } catch (err) {
      return new Response(`Error: ${err.message}`, { status: 500 });
    }
  },
};

Vite 配置（vite.config.ts）

import { defineConfig } from 'vite';
import { cloudflare } from '@cloudflare/vite-plugin';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react(), cloudflare()],
  build: {
    outDir: 'dist',
    emptyOutDir: true,
    minify: true,         // 生产环境压缩
    sourcemap: false,     // 禁用 Source Map
    rollupOptions: {
      output: {
        manualChunks: undefined  // 禁用代码分割（Worker 兼容性优化）
      }
    }
  },
  resolve: {
    alias: { '@': '/src' }  // 路径别名
  }
});

三、Pages 项目部署

初始化与框架支持

• 使用 Vite + React 模板

# 1. 创建项目（使用Vite官方模板）  
npm create vite@latest my-pages --template react-ts  
cd my-pages  

# 2. 安装依赖  
npm install  

# 3. 本地测试（可选）  
npm run dev  # 开发模式  
npm run build  # 生产构建（生成dist目录）  

连接 Cloudflare Pages

• 推送代码到 GitHub（需提前创建空仓库）：

git init
echo "node_modules" >> .gitignore
echo ".env" >> .gitignore
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourname/my-pages.git
git push -u origin main

• 在 Cloudflare 控制台绑定仓库：

  • 进入 Cloudflare Dashboard → Workers & Pages → Create application → Pages

  • 选择你的 Git 提供商（如 GitHub），授权并选择仓库 my-pages

  • 无需手动配置，Cloudflare 会自动检测：

    • 构建命令：npm run build

    • 输出目录：dist

目录结构

my-pages/
├── dist/          # 构建产物（自动生成，无需手动修改）
├── public/        # 静态资产
├── src/           # 代码目录（主要编辑区域）
│   ├── main.tsx   # 应用入口
│   └── App.tsx    # 主组件
├── vite.config.ts # 构建配置（默认无需修改）
└── package.json   # 项目依赖

推荐优化

• 启用生产压缩（在 vite.config.ts 中修改）：

// vite.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
  build: {
    minify: true,  // 压缩代码
    sourcemap: false  // 关闭源码映射
  }
})

• 自定义域名（可选）：

  • 在 Pages 项目设置中点击 Custom Domains，按提示添加域名并配置 DNS。

四、高级功能

D1 数据库操作 **

# 创建数据库
wrangler d1 create my-db

# 执行 SQL 文件
wrangler d1 execute my-db --file=./schema.sql

# 本地测试
wrangler d1 execute my-db --local --file=./test.sql

安全增强

• 敏感变量：通过 wrangler secret put API_KEY 设置

• CSP 头：在 _headers (项目根目录) 文件中定义：

/*
  X-Frame-Options: DENY
  Content-Security-Policy: default-src 'self'

性能监控

# 实时日志（生产环境）
wrangler tail --format=pretty

# 本地开发测试
wrangler dev --remote  # 连接云端资源

安全建议

• 防 DDoS：Cloudflare 默认提供 DDoS 防护，但需在 Dashboard 启用 “Under Attack Mode” 

• WAF 规则：配置自定义防火墙规则拦截恶意流量

• API 安全：避免使用弱密码，推荐 OAuth2 或 API 令牌

 

五、部署流程

Worker 部署

npm run build && wrangler deploy

Pages 部署

wrangler pages deploy ./dist

CI/CD 集成（GitHub Actions 示例）

- name: Deploy to Cloudflare
  run: |
    npm install
    npm run build
    wrangler deploy
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}

本地测试

npm run build && wrangler dev

六、扩展阅读

• 官方 Wrangler 文档

• Vite 插件配置指南 

• D1 数据库实战