StaticQ Headless
| 开发者 |
goonydev
philooo |
|---|---|
| 更新时间 | 2026年9月18日 12:25 |
| PHP版本: | 8.1 及以上 |
| WordPress版本: | 7.1 |
| 版权: | GPLv2 or later |
| 版权网址: | 版权信息 |
详情介绍:
StaticQ Headless turns WordPress into the CMS behind a Cloudflare-hosted Astro frontend. Editors keep the familiar WordPress admin; visitors get static-fast pages served from Cloudflare's edge and a durable R2 cache; and the plugin keeps both sides in sync automatically, without a full rebuild, a cron job, or a manual cache purge on every edit.
When you publish, update, unpublish, or reschedule a post, the plugin works out exactly which URLs changed (the post's permalink, the archives and paginated archives it appears on, the relevant feeds, and the sitemap) and refreshes only those. Nothing else is touched, so a single edit never invalidates your whole site.
Important: everything the plugin does runs against your own Cloudflare and GitHub accounts, using credentials you provide. StaticQ Headless does not send your content or credentials to any StaticQ-operated server. There is no telemetry and no phone-home. See External services below.
What it does
- Per-URL cache invalidation. On each editorial change the plugin computes the impacted URL set with a dedicated URL-impact engine (post, home archive, term archives with correct pagination, author archive, feeds, sitemap) and dispatches just those URLs to a small Cloudflare Worker you deploy from the setup wizard (the "receiver"). The receiver is what purges Cloudflare's edge cache for those URLs, or drops the stored copy in R2 so the frontend re-renders it on the next request. WordPress only ever sends the list of changed URLs, so your WordPress install never needs Cloudflare cache-purge permissions.
- Two-layer edge delivery. The Astro frontend serves pages from Cloudflare's edge cache backed by a durable R2 store, so pages stay fast even after the edge cache evicts them, and cold renders are smoothed out.
- Managed Astro frontend deploy. From wp-admin you connect a GitHub repository (or create a new private one, generated from the public StaticQ Astro starter template so GitHub populates it server-side, with no local git binary and nothing written to your WordPress server), provisions the Cloudflare Worker and R2 bucket, syncs the GitHub Actions variables and secrets, and triggers the deploy. From then on, editing the frontend is a normal
git push. - REST "speed layer" for Astro. Batched-query REST endpoints under
/wp-json/sqheadless/v1/(site config, homepage, archive, single, SEO head, sitemap) collapse WordPress's_embedN+1 fan-out into a handful of SQL queries, for much faster SSR on media-heavy archives. The frontend uses them automatically and falls back to standard WordPress REST when they are absent. - Cache warmup. Prime the edge cache by enumerating every archive and post URL and dispatching them ahead of your visitors.
- Rendered-content cache (optional). Persists rendered post HTML on the WordPress side and re-renders only when the post changes, smoothing cold-render spikes on shortcode- and gallery-heavy content.
- SEO-plugin aware. If Rank Math or Yoast is active, the frontend uses that plugin's own
<head>and structured data; breadcrumb schema is filled in when your SEO plugin does not emit it. No SEO plugin required. - Built-in tutorials. Step-by-step guides ship inside the plugin under StaticQ Headless → Tutorials, always matching your installed version, including how to bring your own Astro templates into the deploy pipeline.
- Extensible. A documented action and a set of filters let you add URLs to the refresh set, register custom pages, or observe every editorial event. A Refresh Simulator dry-runs the engine with your hooks so you can see exactly what an edit would invalidate.
安装:
- Upload the
staticq-headlessfolder to/wp-content/plugins/, or install the plugin ZIP from Plugins → Add New → Upload Plugin. - Activate the plugin through the Plugins screen.
- Open StaticQ Headless → Settings. The Setup tab walks you through connecting Cloudflare and deploying the receiver Worker.
- Open StaticQ Headless → Astro Setup and follow the wizard to connect or create a GitHub repository and deploy the Astro frontend.
- New to it? StaticQ Headless → Tutorials has step-by-step guides.
wp-config.php (above the "That's all, stop editing!" line) instead of storing them in the database. When a constant is defined it takes precedence and the matching field renders read-only.
define( 'SQHEADLESS_CF_API_TOKEN', '...' );
define( 'SQHEADLESS_CF_ACCOUNT_ID', '...' );
define( 'SQHEADLESS_CF_ZONE_ID', '...' );
define( 'SQHEADLESS_PER_URL_SECRET', '...' );
For the managed Astro deploy, a GitHub token constant is used:
define( 'SQHEADLESS_AA_GITHUB_TOKEN', 'ghp_...' );
Additional optional constants (receiver-only tokens, site-gate cookies, per-install worker/bucket suffix) are documented in the plugin's docs.
Requirements
- WordPress 6.4 or newer, PHP 8.1 or newer.
- A Cloudflare account (Workers + R2) for the edge delivery side.
- A GitHub account and a classic personal access token with
repoandworkflowscopes, for deploying and updating the Astro frontend. - PHP libsodium (bundled with PHP 7.2+) is used to encrypt GitHub Actions secrets; if it is unavailable the wizard falls back to manual guidance.
- No shell access,
proc_open, or git binary is required.
屏幕截图:
常见问题:
Does StaticQ Headless host my site?
No. It deploys to your Cloudflare account and your GitHub repository. You own the infrastructure and the code.
Does it send my content or credentials to StaticQ?
No. The plugin only contacts your own Cloudflare and GitHub accounts (endpoints you configure) and the receiver URL you set. There is no telemetry and no author-operated service. See External services.
Do I have to use the StaticQ Astro starter as-is?
No. It is a starting point: you can replace its pages and components with your own Astro design and deploy through the same pipeline, as long as your project keeps the plugin's caching contract (the edge/R2 middleware, cache-key module, and WordPress data client the starter ships with). The built-in Tutorials cover this.
Do I need the GitHub and Cloudflare setup?
Yes, for the headless setup this plugin is built for. The fast edge + R2 delivery comes from the Cloudflare Worker and the Astro frontend, and the frontend is deployed and kept in sync through GitHub. (Internally the invalidation engine simply POSTs the changed URLs to a receiver URL, but the supported, complete experience is the Cloudflare + Astro pipeline.)
Is a full rebuild triggered on every edit?
No. That is the point: the plugin computes the specific URLs a change affects and refreshes only those, so publishing costs the same whether the site has fifty pages or fifty thousand.
Does it require shell access or proc_open?
No. Repository creation and the starter push happen over the GitHub API. Nothing is executed on your server.
Which SEO plugins are supported?
Rank Math and Yoast are detected automatically and their <head> and schema are used by the frontend. Neither is required; the plugin fills in breadcrumb structured data when the SEO plugin does not.
How do I extend which URLs get refreshed?
Use the sqheadless/object_urls, sqheadless/affected_objects, and sqheadless/static_archive_urls filters (and the sqheadless/content_change action to observe events). The Refresh Simulator on the Cache tab dry-runs your hooks and shows the exact URL list. A full reference ships with the plugin.
更新日志:
1.0.0
- Initial release.
- In-admin tutorials: a simple, AI-agent-first track (default) and a full advanced track with the reference docs, all readable under StaticQ Headless → Tutorials.
- Brand section: set the site logo from the plugin (theme-independent; feeds the site-config endpoint and stays in sync with the theme's own logo).
- Live "Last deploy" status on the Astro tab: green check / red cross / in-progress, run number, date, and a link to the GitHub Actions run.
- Warmup URL-list export (CSV/JSON) and a per-URL warmup outcome log.
- Per-URL cache invalidation engine (post, archives with pagination, author, feeds, sitemap), dispatching either an edge purge or a render-to-R2 warm fetch.
- HMAC-signed, timestamped dispatch to a user-configured receiver.
- Two-layer edge delivery (Cloudflare edge cache backed by durable R2) via the StaticQ Astro starter frontend.
- Cache warmup and priming.
- REST speed-layer endpoints under
/wp-json/sqheadless/v1/for fast Astro SSR, with graceful fallback to standard WP REST. - Optional rendered-content cache.
- Password-protected posts are never exposed through the speed-layer endpoints:
contentandexcerptcome back empty withprotectedset, matching WordPress core's own REST behaviour. - Managed Astro frontend deploy over the GitHub API (generate a repo from the public StaticQ starter template or connect an existing one, provision Cloudflare Worker + R2, sync CI variables and secrets, trigger deploy), with no git binary or proc_open. No frontend code ships inside the plugin.
- Rank Math and Yoast head and structured-data passthrough, with automatic breadcrumb schema fallback.
- Refresh Simulator and extension hooks (
sqheadless/content_change,sqheadless/object_urls,sqheadless/affected_objects,sqheadless/static_archive_urls,sqheadless/impact_urls). - Built-in, version-matched tutorials in wp-admin.