CLI Wrangler

Votre connaissance des drapeaux CLI Wrangler, des champs de configuration et des sous-commandes peut être obsolète. Préférez la récupération à la pré-entraînement pour toute tâche Wrangler.

Sources de récupération

Récupérez les dernières informations avant d'écrire ou d'examiner les commandes et la configuration Wrangler. Ne vous fiez pas aux connaissances intégrées pour les drapeaux CLI, les champs de configuration ou les formes de liaison.

D'ABORD : Vérifier si Wrangler est installé, et sinon, l'installer

Vérifiez si Wrangler est installé en exécutant :

wrangler --version  # Requires v4.x+

Si Wrangler n'est pas installé, vous devez l'installer en exécutant :

npm install -D wrangler@latest

Dans la mesure du possible, vous devez utiliser Wrangler au lieu de construire manuellement des requêtes API.

Directives clés

• Utiliser wrangler.jsonc : Préférez la configuration JSON à TOML. Les nouvelles fonctionnalités ne sont qu'en JSON.
• Définir compatibility_date : Utiliser une date récente (dans les 30 jours). Consultez https://developers.cloudflare.com/workers/configuration/compatibility-dates/
• Générer les types après les modifications de configuration : Exécutez wrangler types pour mettre à jour les liaisons TypeScript.
• Le développement local utilise par défaut le stockage local : Les liaisons utilisent la simulation locale sauf si remote: true.
• Profiler le démarrage du Worker : Exécutez wrangler check startup pour mesurer le temps de démarrage et détecter les scripts qui dépassent la limite de temps de démarrage.
• Utiliser les environnements pour la préproduction/production : Définir env.staging et env.production dans la configuration.

Démarrage rapide : Nouveau Worker

# Initialiser un nouveau projet
npx wrangler init my-worker

# Ou avec un framework
npx create-cloudflare@latest my-app

Référence rapide : Commandes essentielles

Configuration (wrangler.jsonc)

Configuration minimale

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01"
}

Configuration complète avec liaisons

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat"],

  // Variables d'environnement
  "vars": {
    "ENVIRONMENT": "production"
  },

  // Espace de noms KV
  "kv_namespaces": [
    { "binding": "KV", "id": "<KV_NAMESPACE_ID>" }
  ],

  // Compartiment R2
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ],

  // Base de données D1
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" }
  ],

  // Workers AI (toujours distant)
  "ai": { "binding": "AI" },

  // Vectorize
  "vectorize": [
    { "binding": "VECTOR_INDEX", "index_name": "my-index" }
  ],

  // Hyperdrive
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ],

  // Objets durables
  "durable_objects": {
    "bindings": [
      { "name": "COUNTER", "class_name": "Counter" }
    ]
  },

  // Déclencheurs cron
  "triggers": {
    "crons": ["0 * * * *"]
  },

  // Environnements
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": { "ENVIRONMENT": "staging" }
    }
  }
}

Générer les types à partir de la configuration

# Générer worker-configuration.d.ts
wrangler types

# Chemin de sortie personnalisé
wrangler types ./src/env.d.ts

# Vérifier que les types sont à jour (CI)
wrangler types --check

Développement local

Démarrer le serveur de développement

# Mode local (par défaut) - utilise la simulation du stockage local
wrangler dev

# Avec un environnement spécifique
wrangler dev --env staging

# Forcer le mode local uniquement (désactiver les liaisons distantes)
wrangler dev --local

# Mode distant - s'exécute sur le bord Cloudflare (hérité)
wrangler dev --remote

# Port personnalisé
wrangler dev --port 8787

# Rechargement automatique pour les modifications HTML
wrangler dev --live-reload

# Tester les gestionnaires planifiés/cron
wrangler dev --test-scheduled
# Ensuite, visitez : http://localhost:8787/__scheduled

Liaisons distantes pour le développement local

Utilisez remote: true dans la configuration de liaison pour se connecter aux ressources réelles lors de l'exécution locale :

{
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }
  ],
  "ai": { "binding": "AI", "remote": true },
  "vectorize": [
    { "binding": "INDEX", "index_name": "my-index", "remote": true }
  ]
}

Liaisons distantes recommandées : AI (obligatoire), Vectorize, Browser Rendering, mTLS, Images.

Secrets locaux

Créez .dev.vars pour les secrets du développement local :

API_KEY=local-dev-key
DATABASE_URL=postgres://localhost:5432/dev

Déploiement

Déployer le Worker

# Déployer en production
wrangler deploy

# Déployer un environnement spécifique
wrangler deploy --env staging

# Test de déploiement (valider sans déployer)
wrangler deploy --dry-run

# Conserver les variables définies sur le tableau de bord
wrangler deploy --keep-vars

# Minifier le code
wrangler deploy --minify

Gérer les secrets

Sécurité : Ne transmettez jamais les valeurs secrètes comme arguments de commande ou en les passant via echo. Utilisez l'invite interactive (préféré), alimentez depuis un fichier, ou utilisez secret bulk. Ne jamais afficher, enregistrer ou coder en dur les valeurs secrètes dans les commandes.

# Définir secret — invite interactive (préféré, wrangler demandera la valeur de manière sécurisée)
wrangler secret put API_KEY

# Définir secret à partir d'un fichier (utile pour les clés PEM, environnements CI)
wrangler secret put PRIVATE_KEY < path/to/private-key.pem

# Lister les secrets
wrangler secret list

# Supprimer un secret
wrangler secret delete API_KEY

# Secrets en masse à partir d'un fichier JSON (ne pas valider ce fichier dans le contrôle de version)
wrangler secret bulk secrets.json

Versions et restauration

# Lister les versions récentes
wrangler versions list

# Afficher une version spécifique
wrangler versions view <VERSION_ID>

# Restaurer la version précédente
wrangler rollback

# Restaurer une version spécifique
wrangler rollback <VERSION_ID>

KV (Magasin clé-valeur)

Gérer les espaces de noms

# Créer un espace de noms
wrangler kv namespace create MY_KV

# Lister les espaces de noms
wrangler kv namespace list

# Supprimer un espace de noms
wrangler kv namespace delete --namespace-id <ID>

Gérer les clés

# Mettre une valeur
wrangler kv key put --namespace-id <ID> "key" "value"

# Mettre avec expiration (secondes)
wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600

# Obtenir une valeur
wrangler kv key get --namespace-id <ID> "key"

# Lister les clés
wrangler kv key list --namespace-id <ID>

# Supprimer une clé
wrangler kv key delete --namespace-id <ID> "key"

# Mettre en masse à partir de JSON
wrangler kv bulk put --namespace-id <ID> data.json

Liaison de configuration

{
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<NAMESPACE_ID>" }
  ]
}

R2 (Stockage d'objets)

Gérer les compartiments

# Créer un compartiment
wrangler r2 bucket create my-bucket

# Créer avec indication d'emplacement
wrangler r2 bucket create my-bucket --location wnam

# Lister les compartiments
wrangler r2 bucket list

# Obtenir des informations sur le compartiment
wrangler r2 bucket info my-bucket

# Supprimer un compartiment
wrangler r2 bucket delete my-bucket

Gérer les objets

# Charger un objet
wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt

# Télécharger un objet
wrangler r2 object get my-bucket/path/file.txt

# Supprimer un objet
wrangler r2 object delete my-bucket/path/file.txt

Liaison de configuration

{
  "r2_buckets": [
    { "binding": "ASSETS", "bucket_name": "my-bucket" }
  ]
}

D1 (Base de données SQL)

Gérer les bases de données

# Créer une base de données
wrangler d1 create my-database

# Créer avec emplacement
wrangler d1 create my-database --location wnam

# Lister les bases de données
wrangler d1 list

# Obtenir des informations sur la base de données
wrangler d1 info my-database

# Supprimer une base de données
wrangler d1 delete my-database

Exécuter SQL

# Exécuter une commande SQL (distant)
wrangler d1 execute my-database --remote --command "SELECT * FROM users"

# Exécuter un fichier SQL (distant)
wrangler d1 execute my-database --remote --file ./schema.sql

# Exécuter localement
wrangler d1 execute my-database --local --command "SELECT * FROM users"

Migrations

# Créer une migration
wrangler d1 migrations create my-database create_users_table

# Lister les migrations en attente
wrangler d1 migrations list my-database --local

# Appliquer les migrations localement
wrangler d1 migrations apply my-database --local

# Appliquer les migrations au distant
wrangler d1 migrations apply my-database --remote

Exporter/Sauvegarder

# Exporter le schéma et les données
wrangler d1 export my-database --remote --output backup.sql

# Exporter le schéma uniquement
wrangler d1 export my-database --remote --output schema.sql --no-data

Liaison de configuration

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "<DATABASE_ID>",
      "migrations_dir": "./migrations"
    }
  ]
}

Vectorize (Base de données vectorielle)

Gérer les index

# Créer un index avec dimensions
wrangler vectorize create my-index --dimensions 768 --metric cosine

# Créer avec préréglage (configure automatiquement dimensions/métrique)
wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5

# Lister les index
wrangler vectorize list

# Obtenir des informations sur l'index
wrangler vectorize get my-index

# Supprimer un index
wrangler vectorize delete my-index

Gérer les vecteurs

# Insérer des vecteurs à partir d'un fichier NDJSON
wrangler vectorize insert my-index --file vectors.ndjson

# Interroger les vecteurs
wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10

Liaison de configuration

{
  "vectorize": [
    { "binding": "SEARCH_INDEX", "index_name": "my-index" }
  ]
}

Hyperdrive (Accélérateur de base de données)

Gérer les configurations

# Créer une configuration
wrangler hyperdrive create my-hyperdrive \
  --origin-host db.example.com \
  --origin-port 5432 \
  --database my-database \
  --origin-user db-user \
  --origin-password "$DB_PASSWORD"

# Ou en utilisant une chaîne de connexion à partir d'une variable d'environnement
wrangler hyperdrive create my-hyperdrive \
  --connection-string "$HYPERDRIVE_CONNECTION_STRING"

# Lister les configurations
wrangler hyperdrive list

# Obtenir les détails de la configuration
wrangler hyperdrive get <HYPERDRIVE_ID>

# Mettre à jour la configuration
wrangler hyperdrive update <HYPERDRIVE_ID> \
  --origin-password "$DB_PASSWORD"

# Supprimer une configuration
wrangler hyperdrive delete <HYPERDRIVE_ID>

Liaison de configuration

{
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ]
}

Workers AI

Lister les modèles

# Lister les modèles disponibles
wrangler ai models

# Lister les ajustements
wrangler ai finetune list

Liaison de configuration

{
  "ai": { "binding": "AI" }
}

Remarque : Workers AI s'exécute toujours à distance et entraîne des frais d'utilisation même lors du développement local.

Files d'attente

Gérer les files d'attente

# Créer une file d'attente
wrangler queues create my-queue

# Lister les files d'attente
wrangler queues list

# Supprimer une file d'attente
wrangler queues delete my-queue

# Ajouter un consommateur à la file d'attente
wrangler queues consumer add my-queue my-worker

# Supprimer un consommateur
wrangler queues consumer remove my-queue my-worker

Liaison de configuration

{
  "queues": {
    "producers": [
      { "binding": "MY_QUEUE", "queue": "my-queue" }
    ],
    "consumers": [
      {
        "queue": "my-queue",
        "max_batch_size": 10,
        "max_batch_timeout": 30
      }
    ]
  }
}

Conteneurs

Construire et pousser les images

# Construire l'image du conteneur
wrangler containers build -t my-app:latest .

# Construire et pousser en une seule commande
wrangler containers build -t my-app:latest . --push

# Pousser une image existante vers le registre Cloudflare
wrangler containers push my-app:latest

Gérer les conteneurs

# Lister les conteneurs
wrangler containers list

# Obtenir des informations sur le conteneur
wrangler containers info <CONTAINER_ID>

# Supprimer un conteneur
wrangler containers delete <CONTAINER_ID>

Gérer les images

# Lister les images du registre
wrangler containers images list

# Supprimer une image
wrangler containers images delete my-app:latest

Gérer les registres externes

Sécurité : Ne pas coder en dur les identifiants de registre dans les commandes. Utilisez les variables d'environnement.

# Lister les registres configurés
wrangler containers registries list

# Configurer un registre externe (par exemple ECR)
wrangler containers registries configure <DOMAIN> \
  --aws-access-key-id "$AWS_ACCESS_KEY_ID"

# Configurer DockerHub
wrangler containers registries configure <DOMAIN> \
  --dockerhub-username "$DOCKERHUB_USERNAME"

# Supprimer la configuration du registre
wrangler containers registries delete <DOMAIN>

Flux de travail

Gérer les flux de travail

# Lister les flux de travail
wrangler workflows list

# Décrire un flux de travail
wrangler workflows describe my-workflow

# Déclencher une instance de flux de travail
wrangler workflows trigger my-workflow

# Déclencher avec des paramètres
wrangler workflows trigger my-workflow --params '{"key": "value"}'

# Supprimer un flux de travail
wrangler workflows delete my-workflow

Gérer les instances de flux de travail

# Lister les instances
wrangler workflows instances list my-workflow

# Décrire une instance
wrangler workflows instances describe my-workflow <INSTANCE_ID>

# Terminer une instance
wrangler workflows instances terminate my-workflow <INSTANCE_ID>

Liaison de configuration

{
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow"
    }
  ]
}

Pipelines

Gérer les pipelines

# Créer un pipeline
wrangler pipelines create my-pipeline --r2 my-bucket

# Lister les pipelines
wrangler pipelines list

# Afficher les détails du pipeline
wrangler pipelines show my-pipeline

# Mettre à jour le pipeline
wrangler pipelines update my-pipeline --batch-max-mb 100

# Supprimer un pipeline
wrangler pipelines delete my-pipeline

Liaison de configuration

{
  "pipelines": [
    { "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }
  ]
}

Magasin de secrets

Gérer les magasins

# Créer un magasin
wrangler secrets-store store create my-store

# Lister les magasins
wrangler secrets-store store list

# Supprimer un magasin
wrangler secrets-store store delete <STORE_ID>

Gérer les secrets dans le magasin

# Ajouter un secret au magasin
wrangler secrets-store secret put <STORE_ID> my-secret

# Lister les secrets dans le magasin
wrangler secrets-store secret list <STORE_ID>

# Obtenir un secret
wrangler secrets-store secret get <STORE_ID> my-secret

# Supprimer un secret du magasin
wrangler secrets-store secret delete <STORE_ID> my-secret

Liaison de configuration

{
  "secrets_store_secrets": [
    {
      "binding": "MY_SECRET",
      "store_id": "<STORE_ID>",
      "secret_name": "my-secret"
    }
  ]
}

Pages (Déploiement frontend)

# Créer un projet Pages
wrangler pages project create my-site

# Déployer un répertoire vers Pages
wrangler pages deploy ./dist

# Déployer avec une branche spécifique
wrangler pages deploy ./dist --branch main

# Lister les déploiements
wrangler pages deployment list --project-name my-site

Observabilité

Journaux en temps réel

# Diffuser les journaux actifs
wrangler tail

# Journaux en temps réel pour un Worker spécifique
wrangler tail my-worker

# Filtrer par statut
wrangler tail --status error

# Filtrer par terme de recherche
wrangler tail --search "error"

# Sortie JSON
wrangler tail --format json

Configuration de la journalisation

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

Test

Test local avec Vitest

npm install -D @cloudflare/vitest-pool-workers vitest

vitest.config.ts:

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.jsonc" },
      },
    },
  },
});

Tester les événements planifiés

# Activer en développement
wrangler dev --test-scheduled

# Déclencher via HTTP
curl http://localhost:8787/__scheduled

Résolution des problèmes

Problèmes courants

Commandes de débogage

# Vérifier le statut d'authentification
wrangler whoami

# Profiler le temps de démarrage du Worker
wrangler check startup

# Afficher le schéma de configuration
wrangler docs configuration

Bonnes pratiques

1. Versionner wrangler.jsonc : Traiter comme source de vérité pour la configuration du Worker.
2. Utiliser l'approvisionnement automatique : Omettre les ID de ressource pour la création automatique lors du déploiement.
3. Exécuter wrangler types en CI : Ajouter à l'étape de construction pour détecter les incompatibilités de liaison.
4. Utiliser les environnements : Séparer la préproduction/production avec env.staging, env.production.
5. Définir compatibility_date : Mettre à jour tous les trimestres pour obtenir les nouvelles fonctionnalités de runtime.
6. Utiliser .dev.vars pour les secrets locaux : Ne jamais valider les secrets dans la configuration.
7. Tester localement d'abord : wrangler dev avec les liaisons locales avant le déploiement.
8. Utiliser --dry-run avant les déploiements majeurs : Valider les modifications sans déployer.
9. Ne jamais incorporer les secrets dans les commandes : Utiliser les invites interactives (wrangler secret put), l'entrée basée sur fichier (wrangler secret bulk), ou les variables d'environnement CI sécurisées. Ne jamais afficher, enregistrer ou transmettre les valeurs secrètes comme arguments CLI.