Deploy your Astro Site to Cloudflare Pages
本頁內容尚未翻譯。
You can deploy your Astro project on Cloudflare Pages, a platform for frontend developers to collaborate and deploy static (JAMstack) and SSR websites.
This guide includes:
- How to deploy through the Cloudflare Pages Dashboard
- How to deploy using Wrangler, the Cloudflare CLI
- How to deploy an SSR site using
@astrojs/cloudflare
Prerequisites
Section titled PrerequisitesTo get started, you will need:
- A Cloudflare account. If you don’t already have one, you can create a free Cloudflare account during the process.
- Your app code pushed to a GitHub or a GitLab repository.
How to deploy a site with Git
Section titled How to deploy a site with Git-
Set up a new project on Cloudflare Pages.
-
Push your code to your git repository (GitHub, GitLab).
-
Log in to the Cloudflare dashboard and select your account in Account Home > Pages.
-
Select Create a new Project and the Connect Git option.
-
Select the git project you want to deploy and click Begin setup
-
Use the following build settings:
- Framework preset:
Astro
- Build command:
npm run build
- Build output directory:
dist
- Framework preset:
-
Click the Save and Deploy button.
How to deploy a site using Wrangler
Section titled How to deploy a site using Wrangler- Install Wrangler CLI.
- Authenticate Wrangler with your Cloudflare account using
wrangler login
. - Run your build command.
- Deploy using
npx wrangler pages deploy dist
.
After your assets are uploaded, Wrangler will give you a preview URL to inspect your site. When you log into the Cloudflare Pages dashboard, you will see your new project.
Enabling Preview locally with Wrangler
Section titled Enabling Preview locally with WranglerFor the preview to work, you must install wrangler
It’s then possible to update the preview script to run wrangler
instead of Astro’s built-in preview command:
How to deploy an SSR site
Section titled How to deploy an SSR siteYou can build an Astro SSR site for deployment to Cloudflare Pages using the @astrojs/cloudflare
adapter.
Follow the steps below to set up the adapter. You can then deploy using either of the approaches documented above.
Quick install
Section titled Quick installAdd the Cloudflare adapter to enable SSR in your Astro project with the following astro add
command. This will install the adapter and make the appropriate changes to your astro.config.mjs
file in one step.
Manual install
Section titled Manual installIf you prefer to install the adapter manually instead, complete the following two steps:
-
Add the
@astrojs/cloudflare
adapter to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: -
Add the following to your
astro.config.mjs
file:
Modes
Section titled ModesThere are currently two modes supported when using Pages Functions with the @astrojs/cloudflare
adapter.
-
Advanced mode: This mode is used when you want to run your function in
advanced
mode which picks up the_worker.js
indist
, or a directory mode where pages will compile the worker out of a functions folder in the project root.If no mode is set, the default is
"advanced"
. -
directory mode: This mode is used when you want to run your function in
directory
mode, which means the adapter will compile the client side part of your app the same way, but it will move the worker script into afunctions
folder in the project root. The adaptor will only ever place a[[path]].js
in that folder, allowing you to add additional plugins and pages middleware which can be checked into version control.
Using Pages Functions
Section titled Using Pages FunctionsPages Functions enable you to run server-side code to enable dynamic functionality without running a dedicated server.
To get started, create a /functions
directory at the root of your project. Writing your Functions files in this directory automatically generates a Worker with custom functionality at the predesignated routes. To learn more about writing Functions, see the Pages Functions documentation.
Troubleshooting
Section titled TroubleshootingIf you’re encountering errors, double-check the version of node
you’re using locally (node -v
) matches the version you’re specifying in the environment variable.
Cloudflare requires Node v16.13, which is a more recent version than Astro’s out-of-the-box minimum, so double check you’re using at least v16.13.
Client-side hydration may fail as a result of Cloudflare’s Auto Minify setting. If you see Hydration completed but contains mismatches
in the console, make sure to disable Auto Minify under Cloudflare settings.