Issue Description#

This problem has occurred multiple times during my deployments, and I read all of the issues but found nothing.

Some blog posts fail to render in production (Cloudflare Pages) while working correctly in local development. This results in missing HTML files (e.g., dist/posts/<ID>/index.html) without explicit build errors during the Astro phase.

I initially suspected formatting issues (especially frontmatter and Markdown structure), and spent considerable time debugging and validating content consistency. This included repeatedly checking for syntax errors and eliminating potential parsing issues. After extensive testing, the problem still persisted intermittently, even with clean and validated content.

Based on these observations, it seems more likely that the issue is related to resource constraints (e.g., memory limits in the Cloudflare Pages build environment), rather than purely content formatting errors. The issue is strongly correlated with large local images and complex LaTeX content, leading to “all-or-nothing” failures where existing posts also disappear due to the failed deployment.

It might also be related to Astro’s build process under constrained environments, which means Fuwari has nothing to do with this problem. But I’d also like to share the workarounds I’ve identified so far, and would appreciate any feedback or better approaches to address this issue.

Environment#

• Deployment Platform: Cloudflare Pages
• Node Version: v22.16.0
• Astro Version: v5.13.10
• Fuwari Version: commit 341b6ba
• Package Manager: pnpm@9.14.4
• Cloudflare configuration:

1
Build command: pnpm build
2
Build output: dist
3
Root directory:  `-`
4
Build comments: Enabled
5
Build cache: Disabled
6
Build system version: Version 3

Reproduction#

1. Asset Load: Add multiple posts containing high-resolution images (>1.5MB) in src/content/posts.
2. Concurrent Push: Commit and push a batch of these posts simultaneously to GitHub.
3. Deployment: Observe the Cloudflare Pages build log. The heavy resource demand (Sharp image processing + LaTeX) often exceeds the build environment’s limits, causing silent skips.
4. Verification: Pushing these same posts one by one (individual commits/deployments) or removing large assets often bypasses the issue, confirming a resource/concurrency bottleneck.

Possible Causes#

The Safety Net: Build Integrity Audit#

For those who have the same problem, it is recommended to add a post-build audit script.

This is because Astro (and thus Fuwari) will often complete the build successfully even if some pages were dropped due to worker failures. The resulting site will appear to function normally, but specific posts will be missing from the production build. This audit script acts as a safeguard to ensure every non-draft post is correctly generated before deployment.

1
import fs from 'fs';
2
import path from 'path';
3

4
// Simplified file-system based audit for CI environment
5
const POSTS_DIR = './src/content/posts';
6
const DIST_DIR = './dist/posts';
7

8
const sourcePosts = fs.readdirSync(POSTS_DIR).filter(f =>
9
  fs.statSync(path.join(POSTS_DIR, f)).isDirectory()
10
);
11

12
const missing = [];
13
sourcePosts.forEach(id => {
14
  const mdPath = path.join(POSTS_DIR, id, 'index.md');
15
  if (fs.existsSync(mdPath)) {
16
    const content = fs.readFileSync(mdPath, 'utf-8');
17
    // Robust check for draft status in frontmatter
18
    const isDraft = /draft:\s*true/.test(content);
19
    const htmlPath = path.join(DIST_DIR, id, 'index.html');
20

21
    if (!isDraft && !fs.existsSync(htmlPath)) {
22
      missing.push(id);
23
    }
24
  }
25
});
26

27
if (missing.length > 0) {
28
  console.error(`\x1b[31m[ERROR] Post Rendering Audit Failed!\x1b[0m`);
29
  console.error(`Missing ${missing.length} posts in production build:`);
30
  missing.forEach(id => console.error(` - ${id} (Expected: ${path.join(DIST_DIR, id, 'index.html')})`));
31
  process.exit(1); // Force CI failure
32
} else {
33
  console.log('\x1b[32m[SUCCESS] All posts verified in dist/.\x1b[0m');
34
}

1
"scripts": {
2
 "build": "astro build --concurrency 2 && pagefind --site dist && node scripts/check-dist.js"
3
}

Workarounds & Solutions#

1
astro build --concurrency 2