Skip to main content

Astro

还没翻译译自英文（developers.cloudflare.com）本页 47 段都还没译

Start from CLI: Scaffold an Astro project on Workers, and pick your template.

npm create cloudflare@latest -- my-astro-app --framework=astro
yarn create cloudflare my-astro-app --framework=astro
pnpm create cloudflare@latest my-astro-app --framework=astro

Or just deploy: Create a static blog with Astro and deploy it on Cloudflare Workers, with CI/CD and previews all set up for you.

Deploy to Workers

What is Astro?

Astro is a JavaScript web framework designed for creating websites that display large amounts of content (such as blogs, documentation sites, or online stores).

Astro emphasizes performance through minimal client-side JavaScript - by default, it renders as much content as possible at build time, or on-demand on the "server" - this can be a Cloudflare Worker. “Islands” of JavaScript are added only where interactivity or personalization is needed.

Astro is also framework-agnostic, and supports every major UI framework, including React, Preact, Svelte, Vue, SolidJS, via its official integrations.

Deploy a new Astro project on Workers

  1. Create a new project with the create-cloudflare CLI (C3).

    npm create cloudflare@latest -- my-astro-app --framework=astro
    yarn create cloudflare my-astro-app --framework=astro
    pnpm create cloudflare@latest my-astro-app --framework=astro

    What's happening behind the scenes?

  2. Develop locally.

    After creating your project, run the following command in your project directory to start a local development server.

    npm run dev
    yarn run dev
    pnpm run dev

  3. Deploy your project.

    You can deploy your project to a *.workers.dev subdomain or a custom domain from your local machine or any CI/CD system (including Workers Builds). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly.

    npm run deploy
    yarn run deploy
    pnpm run deploy

Deploy an existing Astro project on Workers

Automatic configuration

Run wrangler deploy in a project without a Wrangler configuration file and Wrangler will automatically detect Astro, generate the necessary configuration, and deploy your project.

npx wrangler deploy
yarn wrangler deploy
pnpm wrangler deploy

Learn more about automatic project configuration.

Manual configuration

If you prefer to configure your project manually, follow the steps below.

If you have a static site

If your Astro project is entirely pre-rendered, follow these steps:

  1. Add a Wrangler configuration file

    In your project root, create a Wrangler configuration file with the following content:

    {
	"name": "my-astro-app",
	// Set this to today's date
	"compatibility_date": "2026-11-02",
	"assets": {
		"directory": "./dist"
	}
}
    name = "my-astro-app"
# Set this to today's date
compatibility_date = "2026-11-02"

[assets]
directory = "./dist"

    What's this configuration doing?

  2. Build and deploy your project

    You can deploy your project to a *.workers.dev subdomain or a custom domain from your local machine or any CI/CD system (including Workers Builds). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly.

    npx astro build
    yarn astro build
    pnpm astro build
    npx wrangler@latest deploy
    yarn dlx wrangler@latest deploy
    pnpx wrangler@latest deploy

If your site uses on demand rendering

If your Astro project uses on demand rendering (also known as SSR), follow these steps:

  1. Install the Astro Cloudflare adapter

    npx astro add cloudflare
    yarn astro add cloudflare
    pnpm astro add cloudflare

    What's happening behind the scenes?

  2. Add a .assetsignore file Create a .assetsignore file in your public/ folder, and add the following lines to it:

    .assetsignore
    _worker.js
_routes.json

  3. Add a Wrangler configuration file

    In your project root, create a Wrangler configuration file with the following content:

    {
	"name": "my-astro-app",
	"main": "./dist/_worker.js/index.js",
    "upload_source_maps": true,
	// Update to today's date
	// Set this to today's date
	"compatibility_date": "2026-11-02",
	"compatibility_flags": ["nodejs_compat"],
	"assets": {
		"binding": "ASSETS",
		"directory": "./dist"
	},
	"observability": {
		"enabled": true
	}
}
    name = "my-astro-app"
main = "./dist/_worker.js/index.js"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-02"
compatibility_flags = [ "nodejs_compat" ]

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

[observability]
enabled = true

    What's this configuration doing?

  4. Build and deploy your project

    You can deploy your project to a *.workers.dev subdomain or a custom domain from your local machine or any CI/CD system (including Workers Builds). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly.

    npx astro build
    yarn astro build
    pnpm astro build
    npx wrangler@latest deploy
    yarn dlx wrangler@latest deploy
    pnpx wrangler@latest deploy

Bindings

Note

You cannot use bindings if you're using Astro to generate a purely static site.

With bindings, your Astro application can be fully integrated with the Cloudflare Developer Platform, giving you access to compute, storage, AI and more. Refer to the bindings overview for more information on what's available and how to configure them.

The Astro docs provide information about how you can access them in your locals.

Sessions

Astro's Sessions API allows you to store user data between requests, such as user preferences, shopping carts, or authentication credentials. When using the Cloudflare adapter, Astro automatically configures Workers KV for session storage.

Wrangler automatically provisions a KV namespace named SESSION when you deploy, so no manual setup is required.

---
export const prerender = false;
const cart = await Astro.session?.get("cart");
---

<a href="/checkout">{cart?.length ?? 0} items</a>

You can customize the KV binding name with the sessionKVBindingName adapter option if you want to use a different binding name.

Custom 404 pages

To serve a custom 404 page for your Astro site, add not_found_handling to your Wrangler configuration:

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

This tells Cloudflare to serve your custom 404 page (for example, src/pages/404.astro) when a route is not found. Read more about static asset routing behavior.

Astro's build configuration

The Astro Cloudflare adapter sets the build output configuration to output: 'server', which means all pages are rendered on-demand in your Cloudflare Worker. If there are certain pages that don't need on demand rendering/SSR, for example static pages such as a privacy policy, you should set export const prerender = true for that page or route to pre-render it. You can read more about on-demand rendering in the Astro docs.

If you want to use Astro as a static site generator, you do not need the Astro Cloudflare adapter. Astro will pre-render all pages at build time by default, and you can simply upload those static assets to be served by Cloudflare.

Node.js requirements

Astro 5.x supports Node.js 18.20.8, Node.js 20.3.0 and later 20.x releases, or Node.js 22.0.0 or later. Astro 6.x and 7.x require Node.js 22.12.0 or later. If you use Workers Builds, its default Node.js version meets these requirements. If you override the default, select a version that meets Astro's Node.js requirements.

Edit on GitHub
AI 翻译查看英文原文