Your Cloudflare Pages env vars do nothing (Direct Upload vs Git build)

The symptom

I set a PUBLIC_ environment variable in the Cloudflare Pages dashboard (Settings, then Environment variables), redeployed, and the built site behaved as if the variable was empty. The value was definitely saved. Re-checking, re-saving and redeploying changed nothing. The variable never reached the build.

What was happening

There are two kinds of Cloudflare Pages project, and they handle environment variables completely differently. In a Git-integrated build, Cloudflare clones your repo and runs the build on its own infrastructure, injecting the dashboard env vars into that build, which is what most docs and tutorials assume. In a Direct Upload project the build happens somewhere else, a GitHub Action or a local wrangler pages deploy, and only the finished dist/ is uploaded. Cloudflare never runs your build, so the dashboard variables are never present when your bundler runs, and for Astro or Vite, which inline PUBLIC_ / VITE_ values at build time, the value gets baked in as empty.

My project deployed through a GitHub Action (cloudflare/wrangler-action), so it was Direct Upload, and the Pages dashboard env-var screen was decorative for build purposes.

The fix

Set the variable where the build runs. For a GitHub Action, that’s the workflow, on the build step:

# .github/workflows/deploy.yml
      - run: npm ci
      - run: npm run build
        env:
          PUBLIC_BUTTONDOWN_USERNAME: basedev   # public value, fine inline
      - uses: cloudflare/wrangler-action@v3
        with:
          command: pages deploy dist --project-name=my-site

For a secret, reference a repo secret instead of inlining it: ${{ secrets.MY_VAR }}. A PUBLIC_ / VITE_ variable is consumed at build time, so it has to exist in the environment that runs npm run build, which for Direct Upload is your CI.

The lesson

If your Pages project is Direct Upload, meaning you deploy a prebuilt dist, the dashboard’s Environment variables never touch your build. Put build-time vars in the place that runs the build, your CI workflow. The dashboard env-var screen only matters for Git-integrated builds and for runtime Pages Functions.