Comment résoudre le problème de l'IA qui casse l'environnement d'exécution de Cloudflare Workers

Les agents d'IA importent des modules intégrés Node.js comme fs, crypto et path dans Cloudflare Workers, ce qui provoque des erreurs d'exécution car l'environnement d'exécution de Workers n'est pas Node.js.

L’agent écrit du code qui fonctionne localement sous Node.js mais échoue au déploiement ou à l’exécution dans Cloudflare Workers, car l’environnement d’exécution de Workers est un isolat V8 — pas Node.js.

Le symptôme

L’agent importe des modules intégrés Node.js ou des packages npm qui nécessitent en interne des API Node.js.

// worker.ts — WRONG
import { createHash } from "crypto";          // Node built-in — not available
import { readFileSync } from "fs";            // Node built-in — not available
import { resolve } from "path";              // Node built-in — not available
import { IncomingMessage } from "http";      // Node built-in — not available

export default {
  async fetch(request: Request, env: Env) {
    const hash = createHash("sha256").update("data").digest("hex");
    return new Response(hash);
  },
};
// Error at runtime: Cannot read properties of undefined (reading 'createHash')

Pourquoi cela se produit

La plupart des données d’entraînement des agents ciblent Node.js. Le modèle sait que crypto, fs et path fonctionnent pour le hachage, l’accès aux fichiers et la manipulation des chemins, donc il les utilise. Il ne distingue pas l’environnement d’exécution de Workers de Node.js sauf indication explicite.

Comment le repérer

import ... from "crypto" / "fs" / "path" / "http" / "stream" dans les fichiers Worker.
wrangler dev fonctionne mais wrangler deploy génère un avertissement de bundling concernant des modules Node.js non résolus.
La section des indicateurs de compatibilité Wrangler dans wrangler.toml est manquante ou utilise une date antérieure au 2022-11-30.
Dépendances qui utilisent en interne require("node:...") sans un shim de compatibilité Workers.

Comment le corriger

Utilisez les API Web Standard — elles sont disponibles nativement dans Workers.

// worker.ts — CORRECT
export default {
  async fetch(request: Request, env: Env) {
    // Web Crypto API — standard, available in Workers
    const encoder = new TextEncoder();
    const data = encoder.encode("data");
    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
    const hashArray = Array.from(new Uint8Array(hashBuffer));
    const hash = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
    return new Response(hash);
  },
};

# wrangler.toml — enable Node.js compat shims for packages that need them
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]

[ ] No imports from "crypto", "fs", "path", "http", "stream", "os", "buffer" (use node: prefix + nodejs_compat flag if unavoidable)
[ ] Use crypto.subtle for hashing/signing (Web Crypto API)
[ ] Use env bindings (KV, R2, D1) instead of fs for storage
[ ] Set compatibility_date to a recent date in wrangler.toml
[ ] Add nodejs_compat flag only for third-party packages that require it
[ ] Run "wrangler deploy --dry-run" to catch bundling errors before deploying

Prompt de correction

This code imports Node.js built-in modules (crypto, fs, path, http) that are
not available in the Cloudflare Workers runtime. Rewrite it using Web Standard
APIs: crypto.subtle for hashing/encryption, the Fetch API for HTTP, and
Cloudflare bindings (KV, R2, D1) for storage. If a third-party dependency
requires Node.js APIs, add nodejs_compat to compatibility_flags in wrangler.toml
and note that in a comment.

Test

# Dry-run deploy to catch Node.js module errors
wrangler deploy --dry-run --outdir dist 2>&1 | grep -i "error\|unresolved\|node:" && echo "FAIL" || echo "OK"

# Check for raw Node built-in imports
grep -rn '^import.*from "(crypto|fs|path|http|stream|os)"' src/ \
  && echo "FAIL: Node.js built-in import found" || echo "OK"