← Cloudflare Workers / workers / wrangler / migration

Migrace z Wrangleru v3 na v4

Wrangler v4 je velké vydání zaměřené na aktualizace podkladových systémů a závislostí spolu s vylepšeními, díky nimž zůstávají příkazy Wrangleru konzistentní a přehledné. Na rozdíl od předchozích hlavních verzí Wrangleru, které byly zásadní přepisy ↗ a přepracovává architekturu ↗ : verze 4 Wrangleru přináší mnohem menší rozsah změn. Pokud Wrangler používáte již dnes, váš pracovní postup se velmi pravděpodobně nezmění.

U většiny uživatelů půjde o upgrade bez nutnosti zásahu (no-op), následující části ale popisují významnější změny a kroky potřebné k migraci.

Chcete-li ve svém projektu Worker přejít na nejnovější verzi Wrangler v4, spusťte:

npm i -D wrangler@4

Po upgradu můžete instalaci ověřit:

npx wrangler --version

• Aktualizovaná zásada podpory Node.js: Node.js v16, jehož podpora skončila (End-of-Life) v roce 2022, již není ve Wrangler v4 podporován. Wrangler se nyní řídí oficiální životní cyklus podpory ↗.

• Aktualizovaná verze esbuild: Wrangler používá esbuild ↗ pro sbalení kódu Workeru před jeho nasazením a dříve byl pevně svázán s esbuild v0.17.19. Wrangler v4 používá esbuild v0.24, což může ovlivnit dynamické importy se zástupnými znaky. Wrangler bude do budoucna pravidelně aktualizovat esbuild verze dodávaná s Wrangler a od esbuild je nástroj s verzí nižší než 1.0.0, proto mohou tyto změny občas zahrnovat i změny narušující zpětnou kompatibilitu ve způsobu fungování bundlování. Zejména můžeme zvýšit esbuild verze ve vedlejší verzi (minor) Wrangler.

• Příkazy standardně používají lokální režim: Všechny příkazy, které lze spustit v místním nebo vzdáleném režimu, nyní ve výchozím nastavení používají místní režim a vyžadují --remote příznak pro dotazy API.

• Zastaralé příkazy a konfigurace odstraněny: Zastaralé příkazy, přepínače a konfigurace byly odstraněny.

Wrangler nyní podporuje pouze verze Node.js odpovídající Oficiální životní cyklus Node.js ↗:

• Podporováno: Current, Active LTS, Maintenance LTS
• Již není podporováno: Node.js v16 (konec podpory v roce 2022)

Testy Wrangleru se na verzi v16 už nespouštějí a uživatelé, kteří tuto verzi stále používají, se mohou setkat s nepodporovaným chováním. Pokud stále používáte Node.js v16, musíte přejít na podporovanou verzi, abyste mohli i nadále využívat podporu a kompatibilitu s Wranglerem.

node --version

Wrangler v4 aktualizuje esbuild z v0.17.19 na v0.24, což přináší vylepšení (například možnost použít using klíčové slovo s RPC) a změny v chování bundlování:

• Dynamické importy: Zástupné importy (wildcard imports), například import('./data/' + kind + '.json')) nyní automaticky zahrnuje všechny odpovídající soubory do balíčku.

Uživatelé spoléhající na wildcard dynamické importy mohou zaznamenat zabalení nechtěných souborů. Před verzí esbuild v0.19, import příkazy s dynamickými cestami (například import('./data/' + kind + '.json')) nezabalil všechny soubory odpovídající glob vzoru (*.json). Pouze soubory výslovně odkazované nebo zahrnuté pomocí find_additional_modules byly sbaleny (bundled). Od esbuild v0.19 nyní importy se zástupnými znaky automaticky sbalují všechny soubory odpovídající vzoru glob. To může vést k nechtěnému sbalení souborů, proto je vhodné se dynamickým importům se zástupnými znaky vyhnout a použít místo nich explicitní importy.

Všechny příkazy nyní běží v ve výchozím nastavení lokální režim. Wrangler nabízí řadu příkazů pro přístup k prostředkům, jako jsou KV a R2, ale dříve nebylo jednotné, zda tyto příkazy běží v lokálním, nebo vzdáleném prostředí. Například D1 ve výchozím nastavení dotazovalo lokální úložiště dat a vyžadovalo --remote příznak pro dotazování přes API. KV se naproti tomu dříve standardně dotazovalo přes API (implicitně pomocí příznaku --remote příznak) a vyžadovalo --local příznak pro dotazování na lokální úložiště dat. Aby bylo chování napříč Wrangler konzistentní, každý příkaz nyní používá --local příznak ve výchozím nastavení a vyžaduje explicitní --remote příznak pro dotazování přes API.

Například:

• Předchozí chování (Wrangler v3): wrangler kv key get ve výchozím nastavení dotazovány vzdáleně.
• Nové chování (Wrangler v4): wrangler kv key get dotazuje lokálně, pokud --remote je zadáno.

Ti, kdo používají wrangler kv key a/nebo wrangler r2 object příkazy pro dotazování nebo zápis do svého datového úložiště budou muset přidat --remote příznak, abyste zopakovali předchozí chování.

grep -rE "wrangler (kv|r2)" --include="*.sh" --include="*.yml" --include="*.yaml" --include="Makefile" --include="package.json" .

# Before (Wrangler v3 - queried remote by default)
wrangler kv key get --binding MY_KV "my-key"

# After (Wrangler v4 - must specify --remote)
wrangler kv key get --binding MY_KV "my-key" --remote

Všechny dříve zastaralé funkce v Wrangler v2 a v Wrangler v3 byly nyní odstraněny. Kromě toho byly nyní odstraněny i následující funkce, které byly označeny jako zastaralé během vydání Wrangler v3:

• Starší Assets (pomocí wrangler dev/deploy --legacy-assets nebo legacy_assets vlastnost konfiguračního souboru). Místo toho doporučujeme migrace na Workers Static Assets.
• Starší kompatibilita s Node.js (pomocí wrangler dev/deploy --node-compat nebo node_compat vlastnost konfiguračního souboru). Místo toho použijte nodejs_compat příznak kompatibility. Zahrnuje to funkcionalitu ze zastaralého node_compat polyfills a nativně implementovaná Node.js API.
• wrangler version. Místo toho použijte wrangler --version pro kontrolu aktuální verze Wrangleru.
• getBindingsProxy() (přes import { getBindingsProxy } from "wrangler"). Místo toho použijte getPlatformProxy() API, která přijímá naprosto stejné argumenty.
• usage_model. Toto již nemá žádný účinek po zavádění Workers Standard Pricing ↗.

# For TOML files
grep -E "(legacy_assets|node_compat|usage_model)\s*=" wrangler.toml

# For JSON files
grep -E "\"(legacy_assets|node_compat|usage_model)\"" wrangler.json wrangler.jsonc

grep -rE "wrangler.*(--legacy-assets|--node-compat)" --include="*.sh" --include="*.yml" --include="*.yaml" --include="Makefile" --include="package.json" .

grep -rE "getBindingsProxy" --include="*.js" --include="*.ts" --include="*.mjs" .