技术栈#

• 框架: Astro 6.0.8
• 样式: Tailwind CSS v4 + @tailwindcss/vite
• 图片处理: Sharp（Astro 内置图片优化）
• 搜索: Pagefind
• 代码高亮: Expressive Code
• 其他: Swup 页面过渡、KaTeX 数学公式、MDX

服务器配置#

• CPU: 4 核
• 内存: 3.8 GiB（实际可用）
• Swap: 无（初始状态）
• 系统: Ubuntu Linux 6.8.0
• 常驻进程: Docker 容器（OpenClaw ~734MB）、宝塔面板（~110MB）、Nginx、containerd、云监控 Agent 等，合计占用约 1.2GB

也就是说，留给构建进程的内存只有 ~2.6GB。

崩溃现象#

1
$ pnpm build
2

3
 generating optimized images
4
   ▶ /_astro/firefly.EzH7fIYR_2kkPj.webp (1/50)
5
   ▶ /_astro/avatar.BcAu2wMi_yT6PR.webp (2/50)
6
   ▶ /_astro/firefly.EzH7fIYR_16B3gR.webp (3/50)
7
Killed
8

9
# exit code: 137

Exit code 137 = 进程收到 SIGKILL，被 Linux OOM Killer 杀掉了。每次都死在 Sharp 图片优化阶段——这个阶段需要将图片解码到内存中进行处理，50 张图片并行处理时内存瞬间飙升。

2.1 内存去哪了？#

通过 ps aux --sort=-%mem 和 docker stats 分析：

3.8G 总内存 - 1.2G 常驻 ≈ 2.6G 可用。而 Astro 构建过程中：

1. Vite 打包阶段: Rollup 并行处理文件、Tree-shaking 分析、CSS 处理，约 800MB-1.2GB
2. 图片优化阶段: Sharp 解码 + 编码多张大图片，内存峰值可达 2-4GB
3. 两者叠加轻松超过 2.6G

2.2 为什么没用到 Swap？#

通过 dmesg 查看 OOM 日志：

1
oom-kill: constraint=CONSTRAINT_NONE, task=node, pid=3089
2
Out of memory: Killed process 3089 (node)
3
  total-vm:102897108kB, anon-rss:2528824kB

关键发现：Swap 虽然已配置，但使用量为 0。原因是 Linux 默认的 vm.swappiness=60，在内存快速消耗的场景下，OOM Killer 可能在 Swap 被充分利用之前就介入了。

3.1 Astro 配置优化（astro.config.mjs）#

1
experimental: {
2
  // Rust 编译器在低内存环境不稳定，禁用
3
  rustCompiler: false,
4
  // 队列渲染会增加并发内存占用，禁用
5
  queuedRendering: { enabled: false },
6
},

1
image: {
2
  layout: "constrained",
3
  service: {
4
    entrypoint: 'astro/assets/services/sharp',
5
    config: {
6
      // 限制输入图片的最大像素数，防止超大图片撑爆内存
7
      limitInputPixels: 268402689,
8
    },
9
  },
10
},

1
swup({
2
  // ...
3
  preload: false, // 禁用预加载，减少构建时内存
4
}),

1
expressiveCode({
2
  // 限制同时处理的代码高亮任务数
3
  maxConcurrentTasks: 2,
4
  // ...
5
}),

1
mdx({
2
  optimize: true, // 启用 MDX 编译优化
3
}),

3.2 Vite/Rollup 构建优化#

1
build: {
2
  rollupOptions: {
3
    maxParallelFileOps: 5, // 默认值通常更高
4
  },
5
}

1
rollupOptions: {
2
  treeshake: {
3
    moduleSideEffects: false,
4
  },
5
}

1
output: {
2
  manualChunks: (id) => {
3
    if (id.includes('node_modules')) {
4
      if (id.includes('@fancyapps/ui')) return 'vendor-fancyapps';
5
      if (id.includes('pagefind')) return 'vendor-pagefind';
6
      if (id.includes('photoswipe')) return 'vendor-photoswipe';
7
      if (id.includes('overlayscrollbars')) return 'vendor-overlayscrollbars';
8
      return 'vendor';
9
    }
10
    if (id.includes('/src/pages/')) return 'pages';
11
  },
12
}

1
build: {
2
  sourcemap: false,          // 不生成 sourcemap
3
  manifest: false,           // 不生成 manifest
4
  reportCompressedSize: false, // 不计算压缩大小
5
  target: 'es2020',          // 更现代的 target，减少 polyfill
6
}

3.3 图标生成脚本优化（generate-icons.js）#

1
const BATCH_SIZE = 50;
2
for (let i = 0; i < files.length; i += BATCH_SIZE) {
3
  const batch = files.slice(i, i + BATCH_SIZE);
4
  for (const file of batch) {
5
    // 处理文件...
6
  }
7
}

1
const ICON_BATCH_SIZE = 20;
2
for (let i = 0; i < iconArray.length; i += ICON_BATCH_SIZE) {
3
  const batch = iconArray.slice(i, i + ICON_BATCH_SIZE);
4
  for (const iconName of batch) {
5
    const svg = await getIconSvg(iconName);
6
    // ...
7
  }
8
  // 每批处理完后强制垃圾回收
9
  if (global.gc) {
10
    global.gc();
11
  }
12
}

1
// 生成完成后清空图标集缓存
2
iconSetCache.clear();

3.4 构建脚本（build-extreme.sh）#

将构建过程分为独立阶段，每个阶段用独立的 Node 进程运行，进程退出后内存自然释放：

1
#!/bin/bash
2
set -e
3

4
# 内存限制
5
export NODE_OPTIONS="--max-old-space-size=2048 --max-semi-space-size=64 --expose-gc"
6

7
# 清理旧缓存
8
rm -rf dist .astro
9

10
# 阶段 1：图标生成（1GB 限制）
11
node --max-old-space-size=1024 --expose-gc scripts/generate-icons.js
12

13
# 阶段 2：Astro 构建（2GB 限制）
14
npx astro build
15

16
# 阶段 3：搜索索引
17
npx pagefind --site dist

关键设计：

• --max-old-space-size=2048: V8 老生代堆内存限制为 2GB，超过时触发 GC 而非无限增长
• --max-semi-space-size=64: 新生代内存限制为 64MB（默认 16MB），适当增大可以减少频繁 GC
• --expose-gc: 暴露 global.gc() 接口，允许手动触发垃圾回收
• 分阶段执行: 图标生成和 Astro 构建在不同进程中运行，互不影响

3.5 package.json 新增脚本#

1
{
2
  "scripts": {
3
    "build": "node --max-old-space-size=2048 scripts/generate-icons.js && astro build && pagefind --site dist",
4
    "build:extreme": "node --max-old-space-size=1536 scripts/generate-icons.js && node --max-old-space-size=2048 ./node_modules/astro/astro.js build && pagefind --site dist",
5
    "build:lowmem": "set NODE_OPTIONS=--max-old-space-size=2048 && pnpm build",
6
    "clean": "rm -rf dist .astro",
7
    "clean:win": "rmdir /s /q dist 2>nul & rmdir /s /q .astro 2>nul"
8
  }
9
}

三级构建策略：

• pnpm build: 标准构建，带基本内存限制
• pnpm build:lowmem: 低内存构建
• pnpm build:extreme: 极致低内存构建，用于 4G 服务器

4.1 --optimize-for-size 不允许在 NODE_OPTIONS 中使用#

1
node: --optimize-for-size is not allowed in NODE_OPTIONS

Node.js 出于安全考虑，部分 V8 flag 不允许通过 NODE_OPTIONS 环境变量传递，只能通过命令行直接传递。解决方案是从 NODE_OPTIONS 中移除，改为直接在 node 命令后面加参数。

4.2 node ./node_modules/.bin/astro 报语法错误#

1
basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
2
          ^^^^^^^
3
SyntaxError: missing ) after argument list

.bin/astro 是一个 shell 脚本包装器，不能用 node 直接执行。正确的方式是用 npx astro build 或者找到真正的入口文件 ./node_modules/astro/bin/astro.mjs。

4.3 Swap 加了但没用上#

添加了 4GB Swap 后，构建仍然 OOM：

1
$ free -h
2
Swap:   4.0Gi   0B   4.0Gi  # Swap 使用量为 0！

原因是默认的 vm.swappiness=60 不够激进。解决方案：

1
# 提高 swappiness，让系统更积极使用 Swap
2
sysctl vm.swappiness=80
3

4
# 允许内存过度分配，延迟 OOM Killer 的介入
5
sysctl vm.overcommit_memory=1

• vm.swappiness=80: 默认值 60 意味着系统倾向于保留物理内存，设为 80 后系统会更积极地将不活跃页面换出到 Swap
• vm.overcommit_memory=1: 默认值 0 是启发式策略，可能在内存快速消耗时过早触发 OOM Killer。设为 1 表示总是允许分配（overcommit），让进程有机会使用 Swap

4.4 Vite 的 optimizeDeps.disabled 警告#

1
(!) Experimental optimizeDeps.disabled and deps pre-bundling during build
2
were removed in Vite 5.1.

Astro 配置中的 optimizeDeps.disabled 选项在 Vite 5.1 后已移除。虽然是警告不影响构建，但后续可以清理掉这个配置。