← Cloudflare Workers / workers / wrangler / migration

Переход с Wrangler v3 на v4

Wrangler v4 представляет собой крупный релиз, посвящённый обновлению базовых систем и зависимостей, а также улучшениям, которые делают команды Wrangler более последовательными и понятными. В отличие от предыдущих крупных версий Wrangler, которые были фундаментальные переработки ↗ и перестраивает архитектуру ↗ : четвёртая версия Wrangler включает гораздо меньше изменений. Если вы уже используете Wrangler, ваш рабочий процесс почти наверняка не изменится.

Большинству пользователей обновление не потребует никаких действий, но в следующих разделах описаны более существенные изменения и шаги по миграции там, где это необходимо.

Чтобы обновиться до последней версии Wrangler v4 в проекте Worker, выполните:

npm i -D wrangler@4

После обновления вы можете проверить установку:

npx wrangler --version

• Обновлённая политика поддержки Node.js: Node.js v16, срок поддержки которого истёк в 2022 году, больше не поддерживается в Wrangler v4. Теперь Wrangler ориентируется на официальный жизненный цикл поддержки ↗.

• Обновлённая версия esbuild: Wrangler использует esbuild ↗ чтобы собирать код Worker перед развёртыванием, и ранее была зафиксирована на esbuild v0.17.19. Wrangler v4 использует esbuild v0.24, что может повлиять на динамические wildcard-импорты. В дальнейшем Wrangler будет периодически обновлять esbuild версия, включенная в Wrangler, и поскольку esbuild ещё не достиг версии 1.0.0, поэтому изменения в работе сборки (bundling) иногда могут ломать обратную совместимость. В частности, мы можем повысить esbuild версию в минорной версии Wrangler.

• По умолчанию команды работают в локальном режиме: Все команды, которые могут выполняться в локальном или удалённом режиме, теперь по умолчанию используют локальный режим и требуют --remote флаг для запросов к API.

• Устаревшие команды и конфигурации удалены: Устаревшие команды, флаги и конфигурации удалены.

Теперь Wrangler поддерживает только версии Node.js, соответствующие официальный жизненный цикл Node.js ↗:

• Поддерживается: Current, Active LTS, Maintenance LTS
• Больше не поддерживается: Node.js v16 (EOL в 2022 году)

Тесты Wrangler больше не запускаются на v16, поэтому пользователи, всё ещё использующие эту версию, могут столкнуться с неподдерживаемым поведением. Чтобы продолжить получать поддержку и совместимость с Wrangler, обновите Node.js v16 до поддерживаемой версии.

node --version

Wrangler v4 обновляет esbuild с v0.17.19 к v0.24, что принесло улучшения (например, возможность использовать using ключевого слова с RPC) и изменения в поведении сборки:

• Динамический импорт: Импорты с подстановочными знаками (wildcard imports), например, import('./data/' + kind + '.json')) теперь автоматически включают все подходящие файлы в сборку.

У пользователей, которые полагаются на динамические импорты с подстановочными знаками, в сборку могут попасть нежелательные файлы. До esbuild v0.19 import инструкции с динамическими путями (например, import('./data/' + kind + '.json')) не включал в сборку все файлы, соответствующие glob-шаблону (*.json). Только файлы, явно указанные или включённые с помощью find_additional_modules были объединены в сборку. Начиная с esbuild v0.19 импорты с подстановочными знаками автоматически включают в сборку все файлы, соответствующие glob шаблону. Это может привести к попаданию в сборку лишних файлов, поэтому вместо динамических импортов с подстановочными знаками рекомендуется использовать явные импорты.

Теперь все команды выполняются в локальный режим по умолчанию. Wrangler имеет много команд для доступа к ресурсам, таким как KV и R2, но раньше эти команды вели себя непоследовательно в том, что касается локального или удалённого окружения выполнения. Например, D1 по умолчанию обращался к локальному хранилищу данных и требовал --remote флаг для запроса через API. KV же раньше по умолчанию запрашивал данные через API, неявно используя флаг --remote флаг) и требовал --local флаг для запроса локального хранилища данных. Чтобы поведение было единообразным во всех командах Wrangler, теперь каждая команда использует --local флаг по умолчанию и требует явного --remote флаг для запроса через API.

Например:

• Предыдущее поведение (Wrangler v3): wrangler kv key get по умолчанию запрашиваются удаленно.
• Новое поведение (Wrangler v4): wrangler kv key get запросы локально, если только --remote указан.

Те, кто использует wrangler kv key и/или wrangler r2 object команды для чтения или записи в своё хранилище данных, потребуется добавить --remote флаг, чтобы воспроизвести прежнее поведение.

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

Все ранее устаревшие функции в Wrangler v2 и в Wrangler v3 теперь удалены. Кроме того, также удалены следующие функции, которые были признаны устаревшими в релизе Wrangler v3:

• Устаревшие статические ресурсы (с использованием wrangler dev/deploy --legacy-assets или legacy_assets свойство файла конфигурации). Вместо этого мы рекомендуем переход на Workers Static Assets.
• Устаревшая совместимость с Node.js (с использованием wrangler dev/deploy --node-compat или node_compat свойство файла конфигурации). Вместо этого используйте nodejs_compat флаг совместимости. Сюда входит функциональность из устаревшего node_compat полифиллы и нативно реализованные Node.js API.
• wrangler version. Вместо этого используйте wrangler --version чтобы проверить текущую версию Wrangler.
• getBindingsProxy() (через import { getBindingsProxy } from "wrangler"). Вместо этого используйте getPlatformProxy() API, который принимает точно такие же аргументы.
• usage_model. Это больше не имеет эффекта после развертывание 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" .