Пошук

Cloudflare Workers: як віддавати статичні файли з підшляху типу /blog без зміни білду

·

У матеріалі Cloudflare Changelog описується оновлення Workers і CLI (Wrangler та cf), яке спрощує віддачу статичних файлів з URL-підшляху, наприклад /blog/, без зміни структури каталогу білду.

Завдання: віддати статичні файли з /blog, не перекладаючи їх у /blog всередині проєкту

Типовий сценарій, який розбирає авторка: є сайт або SPA, що збирається, наприклад, у dist/. Потрібно опублікувати його не з кореня домену, а з префіксом URL, наприклад:

  • example.com/blog/ — для головної сторінки блогу
  • example.com/blog/posts/post1 — для сторінки поста

Раніше, щоб це працювало зі статичними asset'ами Workers, доводилося фізично вкладати файли в підкаталог blog (тобто мати dist/blog/index.html тощо) або підлаштовувати білд під цей підкаталог.

Оновлення додає конфігураційний параметр базового шляху статичних ресурсів. Тепер можна:

  • залишити файли в корені директорії asset'ів (наприклад, dist/index.html)
  • налаштувати публічний префікс URL через конфіг (/blog)

Нове налаштування base_path / basePath у конфігах

Cloudflare додає параметр базового шляху статичних asset'ів у два варіанти конфігурації:

  • assets.base_path — для Wrangler (JSON або TOML конфіг)
  • worker.assets.basePath — для cloudflare.config.ts у форматі cf-config

Цей параметр визначає, з якого URL-префікса буде віддаватися вміст директорії зі статикою, не змінюючи її внутрішню структуру.

Приклад з cloudflare.config.ts (cf CLI)

Варіант для нового формату конфігурації cloudflare.config.ts з використанням cf:

import { defineConfig } from "cf/config";
export default defineConfig({
worker: {
  name: "blog",
  // Set this to today's date
  compatibilityDate: "2026-11-11",
  assets: {
    basePath: "/blog",
  },
},
});

Ключові моменти цього прикладу:

  • worker.name задає ім'я Worker'а (тут blog).
  • compatibilityDate потрібно виставити на поточну дату, щоб Worker працював з актуальним набором можливостей.
  • Блок assets тепер приймає параметр basePath, який і визначає публічний префікс (/blog).

Локальна структура файлів при цьому може залишатися такою:

  • dist/index.html
  • dist/posts/post1.html

Приклад з wrangler.json

Якщо конфігурація ведеться у форматі wrangler.json, авторка показує такий варіант:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "assets": {
    "directory": "./dist",
    "base_path": "/blog"
  }
}

Тут:

  • assets.directory вказує на локальний каталог зі зібраними файлами, наприклад, ./dist.
  • assets.base_path встановлює публічний URL-префікс /blog.

Приклад з wrangler.toml

Для проєктів з TOML-конфігурацією (wrangler.toml) структура задається секцією [assets]:

[assets]
directory = "./dist"
base_path = "/blog"

Семантика та ж сама:

  • directory — шлях до каталогу з білдом.
  • base_path — URL-префікс, з якого віддаються статичні файли.

Маршрутизація запитів з /blog до файлів у dist

Авторка окремо фіксує, як саме Cloudflare зіставляє URL з файлами після введення базового шляху:

  • Запит до /blog/ віддає файл dist/index.html.
  • Запит до /blog/posts/post1 віддає dist/posts/post1.html.
  • Будь-які запити поза /blog/ не вважаються запитами до статичних asset'ів і спрямовуються на Worker (якщо він є).

Таким чином, можна поєднати:

  • звичайний Worker, що обробляє кореневі або інші шляхи
  • і окремий підшлях зі статичним сайтом, опублікованим як assets з base_path

Вимоги до версій Wrangler та cf

Нова опція з'являється не у всіх версіях інструментів CLI. У матеріалі вказані мінімальні версії:

Якщо застосувати параметр base_path чи basePath на старіших версіях, є ризик, що налаштування просто буде проігноровано або спричинить помилки валідації конфігу. Перед міграцією варто оновити CLI.

Як поводяться _headers, _redirects і run_worker_first

У Workers static assets можна керувати додатковою поведінкою через службові файли в каталозі білду, такі як _headers, _redirects і опцію run_worker_first. У тексті наголошується, що всі шляхи в цих файлах вказуються у публічному просторі URL, тобто з урахуванням базового префікса.

Це означає, що при base_path = "/blog" у _headers або _redirects потрібно писати повні шляхи на кшталт:

  • /blog/..., а не просто /...

Якщо цього не зробити, правила не застосуються до реальних запитів користувачів, оскільки Cloudflare зіставляє їх з повним шляхом, що включає /blog.

Те ж стосується run_worker_first: значення вказуються відносно публічних URL з урахуванням базового шляху.

Зв'язка з Cloudflare Vite plugin: параметр Vite base

Окремий момент у статті — збірка через Cloudflare Vite plugin. Якщо фронтенд збирається Vite і публікується під /blog/, потрібно:

  • в конфігурації Workers задати base_path або basePath як /blog
  • додатково виставити Vite base у vite.config на /blog/

Без цього Vite згенерує посилання на статичні ресурси (CSS, JS, зображення) відносно кореня сайту (/), і в продакшн-середовищі ці шляхи не співпадуть з реальним префіксом /blog/. Налаштування base у Vite синхронізує внутрішні посилання застосунку з тим, як Worker віддає файли.

Де почитати докладніше про сабдиректорії

Для більш розгорнутих сценаріїв маршрутизації авторка посилається на окремий розділ документації Cloudflare Workers: Serving a subdirectory. Там розглядаються додаткові варіанти роботи з підшляхами і розширені налаштування маршрутизації.

У підсумку, новий параметр базового шляху дозволяє тримати структуру білду плоскою (файли в корені каталогу asset'ів), але при цьому публікувати її як розділ сайту на кшталт /blog/, з урахуванням статичних заголовків, редиректів і сумісності з Vite.

Джерело: Cloudflare Changelog

Пошук

Закрити