Speed Up VitePress Build for Large Sites

Tested on: VitePress 1.6.3, 520 pages, GitHub Actions ubuntu-latest Before: 8m04s. After: 2m40s.

1. Cache node_modules + Vite cache

.github/workflows/docs.yml:

- uses: actions/cache@v4
  with:
    path: |
      node_modules
      docs/.vitepress/cache
    key: ${{ runner.os }}-vitepress-${{ hashFiles('package-lock.json') }}

VitePress 1.6 uses .vitepress/cache for deps prebundle.

2. Limit Shiki languages

markdown: {
  languages: ['ts', 'javascript', 'json', 'bash', 'html', 'css', 'yaml'],
  theme: { light: 'github-light', dark: 'github-dark' }
}

Default loads many grammars — slow.

3. Skip dead pages

export default defineConfig({
  srcExclude: ['**/draft/**', '**/README.template.md']
})

4. Don't bundle huge assets

Externalize PDFs > 5 MB to R2/S3, link in markdown.

5. NODE_OPTIONS moderate heap

Too small → GC thrash slows build. Sweet spot:

NODE_OPTIONS=--max-old-space-size=4096

6. Profiling locally

DEBUG=vite:* npm run docs:build 2>&1 | tee build.log

My bottleneck: Shiki 62% of time before language filter.

7. Split locales (monorepo)

Build en and zh in matrix parallel jobs → wall clock halved.

Errors

cache restore failed — wrong path

Path must match where vitepress writes cache (check docs root).

Verify

/usr/bin/time -f elapsed:%E npm run docs:build

CI annotation with build duration trend.

Results

Optimization	Savings
Vite cache	90s
Shiki languages	180s
srcExclude drafts	45s
Parallel locales	50% wall time

Result

8m → 2m40s single job. Editors get preview links faster.