Build and deploy
Chinese version · English
xfm build produces plain static files: no Node runtime, no server-side rendering, no process to babysit. That makes hosting cheap — a CDN, an object store, GitHub Pages all work as-is.
Output structure
1 | dist/ |
Pages are directory + index.html, so every URL is a clean /<path>/ — no server rewrite to .html needed.
Three kinds of non-content pages are worth telling apart:
| Kind | Source | In the post list |
|---|---|---|
| Taxonomy page | One per tag / category / series | No |
| Pagination page | /page/2/, /page/3/ |
No |
| Index page | Category index and archive | No |
None of them join the prev / next chain or the feed — otherwise “previous page” would land on an archive listing.
Incremental cache
The cache lives at .xfm/cache.json in the site root, one { hash, html, bodyHtml } entry per page.
A page’s hash combines six parts:
1 | layout | theme fingerprint | config fingerprint | source text | list summary | related posts |
| Part | Why it is in there |
|---|---|
| Source text | Editing the body must re-render |
| Theme fingerprint | Any change under layouts/ or partials/ invalidates everything |
| Config fingerprint | Site title, nav, defaults, markdown options — same |
| Layout name | Switching layouts obviously re-renders |
| List summary | The home page body does not change when posts are added, but its list does |
| Related posts | Editing another post’s tags changes this page’s recommendations |
The last two are the easy misses: early incremental builds served a stale home list after adding a post, and stale recommendations after retagging. Folding them into the hash made both disappear.
Caching only affects rendering; writing still happens (a cache hit takes the HTML from the cache and writes it). The write phase compares first, though: a file identical to the existing output is neither rewritten nor re-mkdired, so dist/ is always complete and a repeat build only touches what changed.
1 | xfm build # production build, incremental by default |
Caching .xfm/ in CI shortens builds noticeably; note that touching the theme invalidates the whole cache by design, not by bug.
Sub-path deployment
When the site lives at https://example.com/blog/, set site.base to '/blog/':
1 | export default { |
The prefix is applied once, at the render exit, covering three sources:
href="/about/"in a template;[link](/about/)in Markdown;- raw HTML you wrote by hand.
site.base also reaches sitemap / feed URLs and the links inside search.json. xfm dev serves the same prefix — the local URL becomes http://127.0.0.1:4173/blog/, so “works locally, 404 in production” surfaces during development.
The dev server itself follows that prefix too: the live-reload stream lives at /blog/__xfm/events, links on the 404 page carry it, and a half-closed browser connection no longer aborts a rebuild. When previewing a sub-path site behind a proxy, do not poll /__xfm/events without the base.
Internally everything uses bare URLs without the base; disk paths and cache keys ignore it, so changing base does not invalidate the cache.
GitHub Pages
A project site (https://<user>.github.io/<repo>/) is a sub-path; inject it from the workflow:
1 | name: Deploy |
On first use, set Settings → Pages → Build and deployment → Source to GitHub Actions.
Note cancel-in-progress: false: Pages allows one deployment at a time, and cancelling a running one leaves half a deployment behind — so queue instead of interrupt.
A user site (the <user>.github.io repository) uses base /; the script above already distinguishes the two.
Netlify and Vercel
Build command npx xfm build, publish directory dist. Both deploy at the domain root by default, so site.base stays '/'.
Netlify’s netlify.toml:
1 | [build] |
Vercel takes the same two values in project settings, or a vercel.json:
1 | { |
Both bring a CDN and HTTPS, so no cache headers are required. Hashed file names only exist under assets/; if you care, give assets/* a long TTL and *.html a no-cache.
Nginx
1 | server { |
The important line is try_files: pages are directories, so /about/ has to reach about/index.html. Without it you get a pile of 404s.
Object storage
Upload dist/ as a whole. The one thing to watch is directory indexing: S3 / OSS / COS need “static website hosting” enabled with index.html as the index document, otherwise /about/ returns 403 or 404.
Upload in two batches:
assets/(hashed or rarely changing) → long cache;*.html,*.xml,*.json→ short cache orno-cache.
Pre-flight checklist
| Check | How |
|---|---|
site.url is set |
Otherwise the sitemap has relative <loc> and crawlers ignore it |
| Home page title is right | Open / and look at <title> |
| Sub-path works | Under a sub-path, both /blog/ and /blog/about/ open |
| Assets return 200 | DevTools network tab, assets/style.css |
| Sitemap count is right | grep -c "<loc>" dist/sitemap.xml |
| No drafts leaked | Search the built output for draft titles |
| Zero dead links | Install deadlinks with strict: true |
| 404 page exists | Visit a made-up URL and see the custom page |
Troubleshooting
Pages load but all styling is gone
Almost always site.base disagreeing with the deployment path. Under a sub-path, base needs both slashes: '/blog/', not 'blog' (the engine corrects it, but do not rely on that).
Home page fine, refreshing a sub-page 404s
The static server’s directory indexing is misconfigured. On Nginx look at try_files; on object storage at the index-document setting.
Template edited, output unchangedxfm dev caches templates by mtime and normally recompiles on save; if it really does not, xfm clean and rebuild. For production builds, check whether CI restored .xfm/cache.json from a previous commit without invalidating it on template changes — the theme fingerprint handles that unless the cache is reused across branches.
Builds are slow and dominated by writes
At a thousand pages, writing is the bottleneck on Windows / NTFS and no generator can optimise it away. Build on Linux, or produce less output.
Non-ASCII paths 404 on directory URLs
Percent-encoded names are decoded when written to disk, so the server sees UTF-8 paths. If a reverse proxy or object store handles encoding differently, check its URL-decoding settings before blaming site.url.
评论