Как да обновим Astro от версия 5 до 7 и да мигрираме сайта от Cloudflare Pages към Workers

Ако имате Astro сайт на Cloudflare Pages и искате да го прехвърлите на Workers, докато го обновявате от версия 5 на 7 – тази статия е за вас. Ще минем през целия процес стъпка по стъпка, с реални команди и обяснения защо правим нещата по този начин.

Много хора се сблъскват с проблеми при тази миграция. Някои от тях са свързани с промените в Astro 7, други – с разликите между Pages и Workers. Целта ми е да ви спестя часовете опити и грешки.

Защо изобщо да мигрираме към Workers?

Cloudflare от известно време насочва развитието към Workers. Pages продължава да работи, но новите възможности и подобренията идват предимно в Workers. При статични сайтове миграцията е сравнително лесна и ви дава:

• По-добър контрол чрез wrangler
• По-лесна интеграция с други Cloudflare услуги (KV, D1, R2 и т.н.)
• По-модерна инфраструктура за бъдещи нужди

За чисто статичен Astro сайт (какъвто е и нашият случай) не е нужно да включвате SSR адаптер. Просто качвате готовите файлове от dist като статични активи.

Подготовка преди да започнете

Преди да пипате каквото и да е, направете следното:

1. Направете пълен backup на проекта (или просто push-нете всичко в Git).

2. Проверете текущата версия на Astro:

   npx astro --version

3. Уверете се, че използвате Node.js 22.12.0 или по-нова версия (Astro 7 изисква това).

4. Запишете си името на текущия Pages проект и custom domain-а (в нашия случай linuxdevops.dev).

Обновяване на Astro от версия 5 към 7

Обновяването не е просто смяна на номера в package.json. Има някои breaking changes, особено около конфигурацията и интеграциите.

1. Обновете зависимостите

Отворете package.json и актуализирайте основните пакети. Ето примерен набор, който работи добре с Astro 7:

{
  "dependencies": {
    "astro": "^7.3.3",
    "@astrojs/mdx": "^8.0.1",
    "@astrojs/sitemap": "^3.7.4",
    "astro-pagefind": "^2.0.1",
    "astro-seo-schema": "^7.0.0",
    "astro-broken-links-checker": "^1.1.0"
  }
}

След това изпълнете:

npm install

Или, ако използвате pnpm / yarn / bun – съответната команда.

2. Проверете astro.config.mjs

В повечето случаи при статичен сайт конфигурацията остава почти същата. Важно е да нямате стар @astrojs/cloudflare адаптер, ако сайтът е чисто статичен. Ако го имате и не използвате SSR – премахнете го.

Примерна минимална конфигурация:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://linuxdevops.dev',
  integrations: [mdx(), sitemap()],
});

Може да ви е интересно още: Инсталиране на Opengist на bg с Docker и Docker Compose.

3. Тествайте локално

npm run build
npm run preview

Ако всичко се билдва без грешки – готови сте за следващата стъпка.

Миграция от Cloudflare Pages към Workers

Сега идва по-интересната част.

Стъпка 1: Инсталирайте Wrangler

npm install -D wrangler@latest

Стъпка 2: Създайте wrangler.jsonc

В корена на проекта създайте файл wrangler.jsonc със следното съдържание:

{
  "name": "linuxdev-fedia",
  "compatibility_date": "2026-10-15",
  "assets": {
    "directory": "./dist"
  }
}

⚠️ Wrangler compatibility_date е добре да е не по-късна от датата на инсталираната версия на wrangler, иначе може да получиte предупреждение.

Ако искате custom 404 страница, разширете секцията assets:

"assets": {
  "directory": "./dist",
  "not_found_handling": "404-page"
}

Стъпка 3: Добавете deploy скрипт

В package.json добавете:

"scripts": {
  "dev": "astro dev",
  "build": "astro build",
  "preview": "astro preview",
  "deploy": "astro build && wrangler deploy"
}

Стъпка 4: Направете първия deploy

npm run deploy

След успешното изпълнение ще получите адрес от вида https://linuxdev-fedia.xxxxx.workers.dev. Отворете го и проверете дали сайтът изглежда правилно.

Прехвърляне на custom domain-а

Това е най-честото място, където хората се объркват. Дори да сте деплойнали успешно Worker-а, домейнът linuxdevops.dev все още сочи към стария Pages проект.

Направете следното, в този ред:

1. Влезте в Cloudflare Dashboard → Workers & Pages.
2. Отворете стария Pages проект → Custom domains и премахнете linuxdevops.dev.
3. Отворете новия Worker → Settings → Domains & Routes → Add → Custom Domain.
4. Въведете linuxdevops.dev и потвърдете.

Промяната обикновено влиза в сила в рамките на няколко секунди. Няма нужда да пипате DNS записите ръчно, ако домейнът е на Cloudflare nameservers.

Може да ви е интересно още: Git и GitHub команди: Пълно практическо ръководство за ежедневието

Често срещани проблеми и решения

Проблем: След deploy сайтът все още се зарежда от Pages.

Решение: Домейнът не е премахнат от Pages проекта. Премахнете го и го добавете към Worker-а.

---

Проблем: Грешка „That domain is already associated with an existing project“.

Решение: Домейнът все още е закачен към Pages. Изтрийте го оттам.

---

Проблем: Build-ът минава, но на workers.dev адреса се показва стара версия.

Решение: Изчистете кеша на браузъра или отворете адреса в инкогнито. Понякога Cloudflare кешира статичните активи агресивно.

---

Проблем: Искате да използвате SSR.

Решение: Тогава трябва да добавите адаптера:

npx astro add cloudflare

и да промените wrangler.jsonc съответно (с поле main и флаг nodejs_compat).

Заключение

Миграцията от Astro 5 към 7 и преминаването от Pages към Workers изглежда страшно в началото, но всъщност се свежда до няколко ясни стъпки:

1. Обновявате зависимостите и тествате build-а.
2. Добавяте wrangler.jsonc и deploy скрипт.
3. Деплойвате към Workers.
4. Прехвърляте custom domain-а от Pages към Worker-а.

След като веднъж го направите, следващите деплойменти стават тривиални с една команда:

npm run deploy

Ако следвате стъпките в реда, описан по-горе, процесът минава гладко. Успех с миграцията!