# 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.

**Type:** Failure  
**Tools:** Cursor, Claude Code, Codex, Windsurf  
**Stack:** Cloudflare, TypeScript  
**Updated:** 2026-06-08

---

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.

```ts
// 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.

```ts
// 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);
  },
};
```

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

```txt
[ ] 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

```txt title="Fix Prompt"
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

```bash
# 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"
```