导航|地址|刷新
Workers Best Practices

!DOCTYPE html>Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/workers/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

Workers

/

Overview

Getting started

CLI

Dashboard

Prompting

Templates

Examples

Tutorials

Best practices

Workers Best Practices

Demos and architectures

Overview

Build an Interactive ChatGPT App

Local development

Overview

Environment variables and secrets

Vite Plugin ↗

Choosing between Wrangler & Vite

Developing with multiple Workers

Adding local data

Supported bindings per development mode

Local Explorer

Share a local dev server

Playground

Configuration

Overview

Workers Sites

Overview

Start from existing

Start from scratch

Start from Worker

Workers Sites configuration

Bindings ↗

Compatibility dates

Compatibility flags

Cron Triggers

Environment variables

Integrations

Overview

APIs

External Services

Multipart upload metadata

Page Rules

PlacementBeta

Routes and domains

Overview

Custom Domains

Routes

workers.dev

Secrets

Versions & deployments

Overview

Deployment management

Preview URLs

Gradual deployments

Overview

Version affinity

With Durable Objects

Version overrides

Rollbacks

CI/CD

Overview

Builds

Overview

Configuration

Automatic pull requests

Git integration

Overview

GitHub integration

GitLab integration

Build image

Build caching

Build branches

Build watch paths

Deploy Hooks

Advanced setups

Event subscriptions

Troubleshooting builds

Builds API reference

Limits & pricing

MCP serverMCP

External CI/CD

Overview

GitHub Actions

GitLab CI/CD

Workers Cache

Overview

Configuration

Cache keys

Purging the cache

Examples

Debugging

Limitations

Runtime APIs

Overview

Remote-procedure call (RPC)

Overview

Lifecycle

Reserved Methods

Visibility and Security Model

TypeScript

Error handling

WebAssembly (Wasm)

Overview

Wasm in JavaScript

Bindings (env)

Overview

AI ↗

Analytics Engine ↗

Assets ↗

Browser Run ↗

D1 ↗

Dispatcher (Workers for Platforms) ↗

Durable Objects ↗

Dynamic Worker Loaders

Environment Variables ↗

Hyperdrive ↗

Images ↗

KV ↗

Media Transformations ↗

mTLS

Queues ↗

R2 ↗

Rate Limiting

Secrets ↗

Secrets Store ↗Beta

Service bindings

Overview

HTTP

RPC (WorkerEntrypoint)

Stream ↗

Vectorize ↗

Version metadataBeta

Workflows ↗

Cache

Console

Context (ctx)

Encoding

EventSource

Fetch

Handlers

Overview

Alarm Handler ↗

Email Handler ↗

Fetch Handler

Queue Handler ↗

Scheduled Handler

Tail Handler

Headers

HTMLRewriter

MessageChannel

Node.js compatibility

Overview

assert

AsyncLocalStorage

Buffer

crypto

Diagnostics Channel

dns

EventEmitter

fs

http

https

net

path

process

Streams

StringDecoder

test

timers

tls

url

util

zlib

Performance and timers

Request

Response

Scheduler

Streams

Overview

ReadableStream

ReadableStream BYOBReader

ReadableStream DefaultReader

TransformStream

WritableStream

WritableStream DefaultWriter

TCP sockets

Web Crypto

Web standards

WebSockets

Static Assets

Overview

Get Started

Configuration and Bindings

Routing

Full-stack application

Single Page Application (SPA)

Static Site Generation (SSG) and custom 404 pages

Worker script

Advanced

Gradual rollouts ↗

HTML handling

Serving a subdirectory

Headers

Redirects

Direct Uploads

Billing and Limitations

Migration Guides

Migrate from Pages to Workers

Migrate from Netlify to Workers

Migrate from Vercel to Workers

Framework guides

Deploy an existing project

Web applications

React + Vite

Astro

React Router (formerly Remix)

Next.js

Vue

RedwoodSDK

TanStack Start

Microfrontends

SvelteKit

Vike

More guides...

Analog

Angular

Docusaurus

Gatsby

Hono

Nuxt

Qwik

SolidBeta

Waku

Mobile applications

Expo

APIs

FastAPI ↗

Hono ↗

AI & agents

Agents SDK ↗

LangChain ↗

Databases

Connect to databases

Analytics Engine ↗

Vectorize (vector database) ↗

Cloudflare D1 ↗

Hyperdrive ↗

3rd Party Integrations

Overview

Neon

PlanetScale

Supabase

Turso

Upstash

Xata

Testing

Overview

Vitest integration

Overview

Write your first test

Recipes and examples

Configuration

Test APIs

Isolation and concurrency

Debugging

Known issues

Migration guides

Migrate from Vitest 3 to Vitest 4

Migrate from Miniflare 2's test environments

Migrate from unstable_dev

Integration test harness

Overview

Get started

Configure the test harness

Prepare test state

Interact with Workers

Integrations

Miniflare

Overview

Get Started

Writing tests

Core

Compatibility Dates

Fetch Events

Modules

Multiple Workers

Queues

Scheduled Events

Variables and Secrets

Web Standards

WebSockets

Developing

Attaching a Debugger

Live Reload

Migrations

Migrating from Version 2

Storage

Cache

D1

Durable Objects

KV

R2

Wrangler's unstable_startWorker()

Observability

Overview

Metrics and analytics

Logs

Overview

Workers Logs

Real-time logs

Tail Workers

Workers Logpush

TracesBeta

Overview

Custom spansBeta

Spans and attributes

Known limitations

DevTools

Overview

Breakpoints

Profiling CPU usage

Profiling Memory

Query Builder

Exporting OpenTelemetry Data

Overview

Export to Honeycomb

Export to Grafana Cloud

Export to Axiom

Export to Sentry

Export to PostHog

MCP serverMCP

Errors and exceptions

Integrations

Sentry

Source maps and stack traces

Wrangler

Overview

Install/Update Wrangler

Migrations

Migrate from Wrangler v3 to v4

Migrate from Wrangler v2 to v3

Migrate from Wrangler v1 to v2

Wrangler v1 (legacy)

Overview

Install / Update

Authentication

Commands

Configuration

Webpack

1. Migrate webpack projects

2. Update to Wrangler v2

API

Commands

Overview

Workers

General commands

Artifacts

Browser

Certificates

Containers

D1

Flagship

Hyperdrive

KV

Pages

Pipelines

Queues

R2

Secrets Store

Tunnel

Vectorize

VPC

Workers for Platforms

Workflows

Authentication profiles

Bundling

Configuration

Custom builds

Deprecations

Environments

System environment variables

Vite plugin

Overview

Get started

Tutorial - React SPA with an API

Reference

API

Static Assets

Debugging

Migrating from wrangler dev

Secrets

Vite Environments

Cloudflare Environments

Non-JavaScript modules

Programmatic configuration

Languages

Overview

JavaScript

Overview

Examples ↗

TypeScript

Overview

Examples ↗

Python WorkersBeta

Overview

The Basics

How Python Workers Work

Foreign Function Interface (FFI)

Standard Library

Examples

Packages

Overview

FastAPI

Langchain

RustBeta

Overview

Supported crates

Platform

Overview

Pricing

Changelog

Overview

Workers (Historic)

Wrangler

Limits

Choose a data or storage product

Betas

Deploy to Cloudflare buttons

Claim deployments (temporary accounts)

Built with Cloudflare button

Known issues

Workers for Platforms ↗

Infrastructure as Code (IaC)

Glossary

Reference

How the Cache works

How Workers works

Migrate from Service Workers to ES Modules

Protocols

Security model

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Workers llms.txt ↗

Workers llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/Workers

/Best practices

/Workers Best Practices

Workers Best Practices

Last updated Jun 3, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewConfiguration Keep your compatibility date current Enable nodejs_compat Generate binding types with wrangler types Store secrets with wrangler secret, not in source Configure environments deliberately Set up custom domains or routes correctlyRequest and response handling Stream request and response bodies Use waitUntil for work after the responseArchitecture Use bindings for Cloudflare services, not REST APIs Use Queues and Workflows for async and background work Use service bindings for Worker-to-Worker communication Use Hyperdrive for external database connections Use Durable Objects for WebSockets Use Workers Static Assets for new projectsObservability Enable Workers Logs and TracesCode patterns Do not store request-scoped state in global scope Always await or waitUntil your PromisesSecurity Use Web Crypto for secure token generation Do not use passThroughOnException as error handlingDevelopment and testing Test with @cloudflare/vitest-pool-workersRelated resources

Best practices for Workers based on production patterns, Cloudflare's own internal usage, and common issues seen across the developer community.

Configuration

Keep your compatibility date current

The compatibility_date controls which runtime features and bug fixes are available to your Worker. Setting it to today's date on new projects ensures you get the latest behavior. Periodically updating it on existing projects gives you access to new APIs and fixes without changing your code.

{ "name": "my-worker", "main": "src/index.ts", // Set this to today's date "compatibility_date": "2026-07-31", "compatibility_flags": ["nodejs_compat"],}

name = "my-worker"main = "src/index.ts"# Set this to today's datecompatibility_date = "2026-07-31"compatibility_flags = [ "nodejs_compat" ]

For more information, refer to Compatibility dates.

Enable nodejs_compat

The nodejs_compat compatibility flag gives your Worker access to Node.js built-in modules like node:crypto, node:buffer, node:stream, and others. Many libraries depend on these modules, and enabling this flag avoids cryptic import errors at runtime.

{ "name": "my-worker", "main": "src/index.ts", // Set this to today's date "compatibility_date": "2026-07-31", "compatibility_flags": ["nodejs_compat"],}

name = "my-worker"main = "src/index.ts"# Set this to today's datecompatibility_date = "2026-07-31"compatibility_flags = [ "nodejs_compat" ]

For more information, refer to Node.js compatibility.

Generate binding types with wrangler types

Do not hand-write your Env interface. Run wrangler types to generate a type definition file that matches your actual Wrangler configuration. This catches mismatches between your config and code at compile time instead of at deploy time.

Re-run wrangler types whenever you add or rename a binding.

npmyarnpnpm

npx wrangler types

yarn wrangler types

pnpm wrangler types

src/index.jsjs// ✅ Good: Env is generated by wrangler types and always matches your config// Do not manually define Env — it drifts from your actual bindingsexport default { async fetch(request, env) { // env.MY_KV, env.MY_BUCKET, etc. are all correctly typed const value = await env.MY_KV.get("key"); return new Response(value); },};

src/index.tsts// ✅ Good: Env is generated by wrangler types and always matches your config// Do not manually define Env — it drifts from your actual bindings
…(内容过长已截断)

------
导航页打开网址