GolOps

Полное руководство по деплою проекта в Cloudflare Workers

Cloudflare Workers - serverless-платформа на edge с низкой задержкой и бесплатным тарифом. Проект можно развернуть в Workers, но из-за ограничений рантайма (лимит пакета 3 MiB после gzip, отсутствие нативного node:fs и т. д.) требуется дополнительная настройка.

Деплой в Cloudflare Workers использует отдельную ветку (feat/cloudflare), где уже есть необходимые Vite-плагины и конфигурация Workers. Работайте именно в этой ветке.

Предварительные условия

Установлен Wrangler CLI
Есть аккаунт Cloudflare

npm install -g wrangler

wrangler login

Процесс деплоя

Переключитесь на ветку Cloudflare

Ветка feat/cloudflare содержит нужные Vite-плагины (ssrOnlyStubs, shikiNoWasm) и конфиг wrangler.jsonc. Держите её в актуальном состоянии относительно main.

git checkout feat/cloudflare
git rebase main

Загрузите переменные окружения

Workers не читают .env, поэтому переменные нужно загрузить в Cloudflare.

Сгенерируйте JSON из .env.production:

grep -v '^#' .env.production | grep '=' | sed 's/^\([^=]*\)=\(.*\)$/"\1": "\2"/' | paste -sd',' | sed 's/^/{/' | sed 's/$/}/' > /tmp/secrets.json

Затем загрузите их:

wrangler secret bulk /tmp/secrets.json
rm /tmp/secrets.json

Переменные с префиксом VITE_ инлайнатся на этапе сборки и не требуют загрузки как secret. Если загрузить их тоже, это не повредит.

Соберите и задеплойте

pnpm run deploy

Команда сначала выполняет vite build, затем wrangler deploy. После успешного деплоя вы увидите URL Worker:

Total Upload: ~13500 KiB / gzip: ~2330 KiB
Deployed vibe-any-tanstack triggers
  https://vibe-any-tanstack.<your-account>.workers.dev

Собственный домен

Откройте Cloudflare Dashboard → Workers & Pages → нужный Worker → Settings → Domains & Routes
Нажмите Add → Custom Domain
Введите свой домен, который уже подключен к Cloudflare DNS

Что изменено в ветке `feat/cloudflare`

По сравнению с main добавлены только два файла:

Файл	Назначение
`wrangler.jsonc`	Конфигурация Workers: имя, compatibility date/flags, entrypoint
`vite.config.ts`	Добавлены `ssrOnlyStubs()`, `shikiNoWasm()` и условная загрузка плагина `cloudflare()`

Оптимизация размера

В бесплатном тарифе Workers действует ограничение 3 MiB gzip. SSR stubs заменяют тяжелые клиентские библиотеки на пустые реализации в SSR-сборке:

beautiful-mermaid, @streamdown/* → пустые реализации
языковые определения shiki → stubs
@shikijs/engine-oniguruma → JavaScript regex engine вместо WASM

Эти stubs влияют только на SSR bundle, а клиентский код продолжает загружать полные библиотеки.

Частые вопросы

Просмотр логов

wrangler tail --format pretty

Просмотр деталей сборки

wrangler deploy --dry-run --outdir .wrangler/dist

`Cannot access 'pg' before initialization`

Эта ошибка означает, что используется pg (node-postgres), а не postgres (postgres.js). В main уже используется Workers-совместимый postgres.js, убедитесь, что ветка feat/cloudflare актуальна относительно main.

Размер сборки больше 3 MiB

Если вы добавляете тяжелые зависимости, добавьте соответствующие stubs в ssrOnlyStubs() в vite.config.ts или переведите зависимость на динамический import.

Cloudflare Workers

Содержание