← Cloudflare for Platforms / cloudflare-for-platforms / workers-for-platforms / configuration

Statické prostředky

Workers for Platforms umožňuje nasazovat frontendové aplikace ve velkém měřítku. Hostováním statických assetů na globální síti Cloudflare dosáhnete rychlejšího načítání po celém světě a odstraníte potřebu externí infrastruktury. Tyto statické assety můžete také kombinovat s dynamickou logikou v Cloudflare Workers, což vašim zákazníkům poskytne plnohodnotný fullstack zážitek.

Hostujte a zpřístupňujte soubory HTML, CSS, JavaScript a média přímo ze sítě Cloudflare, čímž zajistíte rychlé načítání po celém světě. To je ideální pro blogy, vstupní stránky a dokumentační weby.

Zkombinujte hosting prostředků s Cloudflare Workers a vytvářejte tak dynamické, interaktivní aplikace. Ukládejte a načítejte data pomocí Cloudflare KV, D1 a R2 Storage, takže z jediného Workeru obsloužíte front-endové prostředky i backendovou logiku.

Cloudflare automaticky ukládá statické assety do mezipaměti v datacentrech po celém světě, čímž snižuje latenci a uživatelům kdekoli na světě až dvojnásobně zrychluje načítání.

Vaše aplikace se automaticky škálují, aby zvládly vysoký provoz, aniž byste museli infrastrukturu poskytovat nebo spravovat. Cloudflare se v reálném čase dynamicky přizpůsobuje poptávce.

Nasaďte frontendové assets společně se serverovou logikou, vše v rámci Cloudflare Workers. Odpadá tak potřeba samostatného poskytovatele hostingu a proces nasazení je díky tomu jednodušší.

Jako platforma běžně odpovídáte za nahrávání statických assetů jménem svých koncových uživatelů. To obvykle vypadá takto:

1. Váš uživatel nahraje soubory (HTML, CSS, obrázky) přes vaše rozhraní.
2. Vaše platforma komunikuje s API Workers for Platforms a připojuje statické assety ke skriptu User Workeru.

Jakmile od svých uživatelů obdržíte statické soubory (pro nový nebo aktualizovaný web), proveďte následující kroky a připojte soubory k příslušnému User Workeru:

1. Vytvořte Upload Session
2. Nahrát obsah souborů
3. Nasaďte/aktualizujte Worker

Po dokončení těchto kroků budou statická aktiva User Workeru dostupná na globální síti Cloudflare.

Než odešlete jakákoli data souborů, musíte Cloudflare sdělit, které soubory chcete nahrát. Tento seznam souborů se nazývá manifest. Každá položka manifestu obsahuje:

• Cesta k souboru (například "/index.html" nebo "/assets/logo.png")
• Hash (32 hexadecimálních znaků) reprezentující obsah souboru
• Velikost souboru v bajtech

{
	"/index.html": {
		"hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
		"size": 1234
	},
	"/styles.css": {
		"hash": "36b8be012ee77df5f269b11b975611d3",
		"size": 5678
	}
}

Chcete-li zahájit proces nahrávání, odešlete požadavek POST na Create Assets Upload Session Koncový bod API.

POST /accounts/{account_id}/workers/dispatch/namespaces/{namespace}/scripts/{script_name}/assets-upload-session

Parametry cesty:

• namespace: Název dispatch namespace Workers for Platforms
• script_name: Název User Workeru

Do těla požadavku zahrňte objekt JSON, který u každé cesty k souboru uvádí i její hash a velikost. Cloudflare tak pozná, které soubory chcete nahrát, a může zkontrolovat, zda už některé z nich nejsou uloženy.

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME/assets-upload-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  --data '{
    "manifest": {
      "/index.html": {
        "hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
        "size": 1234
      },
      "/styles.css": {
        "hash": "36b8be012ee77df5f269b11b975611d3",
        "size": 5678
      }
    }
  }'

Můžete vypočítat hash SHA-256 obsahu souboru a poté jej zkrátit nebo jinak konzistentně vyjádřit jako 32znakový hexadecimální řetězec. Dbejte na to, abyste to dělali pokaždé stejným způsobem, aby Cloudflare dokázal soubory mezi jednotlivými nahráváními spolehlivě spárovat.

Pokud jsou všechny soubory již uloženy na Cloudflare, odpověď vrátí pouze token JWT. Pokud jsou potřeba nové nebo aktualizované soubory, odpověď vrátí:

• jwt: Token pro nahrávání (platný 1 hodinu), který se použije v požadavku API k nahrání obsahu souboru (krok 2).
• buckets: Pole skupin hashů souborů, které určuje, jaké soubory se mají nahrát společně. Nedávno nahrané soubory se v těchto skupinách neobjeví, protože je Cloudflare už má.

Pokud odpověď z Upload Session API vrátí buckets, znamená to, že máte nové nebo změněné soubory, které je potřeba nahrát do Cloudflare.

Použijte Workers Assets Upload API k přenosu syrových bajtů souboru zakódovaných ve formátu base64 pro všechny chybějící nebo změněné soubory. Po nahrání je Cloudflare uloží, aby je bylo možné později připojit k Uživatelskému Workeru.

Na rozdíl od většiny volání API Cloudflare, která v hlavičce Authorization používají API token platný pro celý účet, nahrání obsahu souborů vyžaduje krátkodobý token JWT vrácený v jwt pole assets-upload-session odpověď.

Zahrňte jej do hlavičky jako token Bearer:

Authorization: Bearer <upload-session-token>

Tento token je platný jednu hodinu a musí být uveden u každého požadavku na nahrání do Workers Assets Upload API.

Soubory musíte odeslat jako multipart/form-data s obsahem kódovaným v base64:

• Název pole: hash souboru (například 36b8be012ee77df5f269b11b975611d3)
• Hodnota pole: řetězec surových bajtů souboru zakódovaný v Base64

Pokud odpověď vaší Upload Session obsahovala jediný "bucket" se dvěma hashi souborů:

"buckets": [
  [
    "08f1dfda4574284ab3c21666d1ee8c7d4",
    "36b8be012ee77df5f269b11b975611d3"
  ]
]

Oba soubory můžete nahrát v jednom požadavku, každý jako pole form-data:

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/assets/upload?base64=true" \
  -H "Authorization: Bearer <upload-session-token>" \
  -F "08f1dfda4574284ab3c21666d1ee8c7d4=<BASE64_OF_INDEX_HTML>" \
  -F "36b8be012ee77df5f269b11b975611d3=<BASE64_OF_STYLES_CSS>"

• <upload-session-token> je token z odpovědi assets-upload-session z kroku 1
• <BASE64_OF_INDEX_HTML> je obsah souboru index.html zakódovaný v Base64
• <BASE64_OF_STYLES_CSS> je obsah souboru styles.css zakódovaný v Base64

Pokud máte více bucketů (například [["hashA"], ["hashB"], ["hashC"]]), možná budete muset tento postup opakovat pro každý bucket, přičemž na skupinu bucketů provedete jeden požadavek.

Jakmile jsou nahrány všechny soubory z manifestu, vrátí se stavový kód 201 bude vrácena, s jwt pole. Tento JWT je finální token "completion", který lze použít k vytvoření nasazení Workeru s touto sadou assetů. Tento token je platný 1 hodinu.

{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"jwt": "<completion-token>"
	}
}

<completion-token> znamená, že Cloudflare úspěšně přijal a uložil obsah souborů uvedený ve vašem manifestu. Tuto hodnotu použijete <completion-token> v kroku 3, abyste dokončili připojení těchto souborů k Workeru.

Jakmile má Cloudflare všechny potřebné soubory (z předchozích kroků nahrávání), musíte je připojit k User Workeru odesláním požadavku PUT na API pro nahrání User Workeru. Tento poslední krok propojí statické assety s User Workerem pomocí completion tokenu, který jste obdrželi po nahrání obsahu souborů.

Volitelná nastavení můžete zadat také pod assets.config pole pro přizpůsobení způsobu doručování souborů (například pro zpracování koncových lomítek v cestách HTML).

curl -X PUT \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer $API_TOKEN" \
  -F 'metadata={
    "main_module": "index.js",
    "assets": {
      "jwt": "<completion-token>",
      "config": {
        "html_handling": "auto-trailing-slash"
      }
    },
    "compatibility_date": "2025-01-24"
  };type=application/json' \
  -F 'index.js=@/path/to/index.js;type=application/javascript'

• "jwt": "<completion-token>" propojí nově nahrané soubory s Workerem
• Zahrnutí "html_handling" (nebo dalších polí v rámci "config") je volitelné a umožňuje přizpůsobit způsob, jakým se poskytují statické soubory
• Pokud se kód Workeru uživatele nezměnil, můžete soubor s kódem vynechat nebo znovu nahrát stejný index.js

Jakmile tento požadavek PUT uspěje, soubory se zpřístupní na User Workeru. Požadavky směrované na tento Worker pak budou obsluhovat nové nebo aktualizované statické assety.

Pokud dáváte přednost přístupu přes CLI a nastavení vaší platformy umožňuje přímé publikování, můžete pomocí Wrangleru nasadit jak kód Workeru, tak statické assety. Wrangler zabalí a nahraje statické assety (ze zadaného adresáře) společně se skriptem Workeru, takže vše spravujete na jednom místě.

Vytvořte nebo aktualizujte svůj Konfigurační soubor Wrangler k určení, kde má Wrangler hledat statické soubory:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-static-site",
	"main": "./src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
	},
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-static-site"
main = "./src/index.js"
# Set this to today's date
compatibility_date = "2026-08-28"

[assets]
directory = "./public"
binding = "ASSETS"

• directory: Místní složka obsahující vaše statické soubory (například ./public).
• binding: Název bindingu, který se v kódu vašeho Workeru používá k odkazování na tato aktiva.

Umístěte své statické soubory (HTML, CSS, obrázky atd.) do zadaného adresáře (v tomto příkladu ./public). Wrangler tyto soubory při publikování Workeru rozpozná a zabalí je.

Pokud na tyto soubory potřebujete odkazovat ve skriptu Workeru, abyste je mohli zpřístupňovat dynamicky, můžete použít ASSETS binding takto:

export default {
	async fetch(request, env, ctx) {
		return env.ASSETS.fetch(request);
	},
};

Spusťte Wrangler a publikujte jím kód Workeru i statické assety:

npx wrangler deploy --name <USER_WORKER_NAME> --dispatch-namespace <NAMESPACE_NAME>

Wrangler automaticky rozpozná vaše statické soubory, sbalí je a nahraje je do Cloudflare společně s kódem vašeho Workeru.