静态站点生成器的架构选型：Gatsby vs VuePress vs VitePress
gatsby、vitepress 和 vuepress 都是流行的静态站点生成器（SSG），但服务于不同的技术栈和场景。gatsby 基于 React 和 GraphQL，适合数据源复杂的大型网站。vuepress 和 vitepress 均基于 Vue，专注于文档和技术博客，其中 vitepress 是 vuepress 的轻量级继任者，利用 Vite 提供更快的构建速度。选择它们通常取决于团队的技术栈（React vs Vue）以及项目的复杂度（通用网站 vs 文档中心）。
npm下载趋势
GitHub Stars 排名
统计详情
Gatsby vs VuePress vs VitePress: 架构、性能与适用场景深度对比
gatsby、vuepress 和 vitepress 都是前端生态中成熟的静态站点生成器，但它们的设计哲学和适用领域截然不同。gatsby 是 React 生态的重量级选手，擅长处理复杂数据；而 vuepress 和 vitepress 则是 Vue 生态的文档利器，后者更侧重于速度。让我们从架构师的角度深入对比它们的核心差异。
🏗️ 核心架构：React 生态 vs Vue 生态
gatsby 深度绑定 React 生态。
- 基于 Webpack 构建（尽管正在向更模块化架构迁移）。
- 所有页面和组件都是 React 组件。
- 适合熟悉 React 的团队。
// gatsby: React 组件即页面
// src/pages/about.js
import React from "react"
export default function About() {
return <div>About Us</div>
}
vuepress 基于 Vue 2 或 Vue 3（v2 版本）。
- v1 版本使用 Webpack，v2 版本默认使用 Vite。
- 页面主要是 Markdown 文件，辅以 Vue 组件。
- 适合 Vue 技术栈团队。
// vuepress: Markdown 中包含 Vue 语法
// docs/about.md
---
title: About
---
# About Us
<ClientOnly>
<MyVueComponent />
</ClientOnly>
vitepress 基于 Vue 3 和 Vite。
- 原生支持 Vite 的高速 HMR 和构建。
- 专为文档优化，去除了通用 SSG 的冗余。
- 适合追求极致性能的 Vue 项目。
// vitepress: 类似的 Markdown 体验，但更轻量
// docs/about.md
---
title: About
---
# About Us
<script setup>
import MyVueComponent from './MyVueComponent.vue'
</script>
<MyVueComponent />
📂 数据层与内容管理：GraphQL vs 前端元数据
gatsby 拥有强大的 GraphQL 数据层。
- 可以在构建时查询任何数据源（CMS、API、文件系统）。
- 数据统一在 GraphQL 层处理，页面通过 query 获取数据。
- 学习曲线较陡，但数据管理能力极强。
// gatsby: 使用 GraphQL 查询数据
// src/pages/index.js
export const query = graphql`
query {
allMarkdownRemark { nodes { frontmatter { title } } }
}
`
export default function Home({ data }) {
return <div>{data.allMarkdownRemark.nodes[0].frontmatter.title}</div>
}
vuepress 使用 Markdown Frontmatter 和局部数据。
- 数据通常直接写在 Markdown 文件头部。
- 可以通过
clientConfig扩展，但没有统一的数据层。 - 适合文档类内容，不适合复杂数据关联。
// vuepress: Frontmatter 定义元数据
// docs/guide.md
---
title: Guide
contributors: ["Alice", "Bob"]
---
# Guide
<p>Contributors: {{ $page.frontmatter.contributors.join(", ") }}</p>
vitepress 同样依赖 Frontmatter，但支持更灵活的 JS 配置。
- 支持在
.md文件中直接使用<script setup>获取数据。 - 可以在构建时通过
transformPageData钩子注入数据。 - 比
vuepress更现代，但依然没有 GraphQL 层。
// vitepress: 在 Markdown 中直接获取数据
// docs/index.md
---
title: Home
---
<script setup>
import { ref, onMounted } from 'vue'
const data = ref(null)
onMounted(async () => { data.value = await fetch('/api/data') })
</script>
<div>{{ data }}</div>
⚙️ 配置与扩展性：复杂灵活 vs 约定优于配置
gatsby 配置非常灵活但复杂。
- 通过
gatsby-config.js管理插件和数据源。 - 通过
gatsby-node.js编程式创建页面。 - 适合需要完全控制构建流程的大型项目。
// gatsby: 编程式创建页面
// gatsby-node.js
exports.createPages = async ({ graphql, actions }) => {
const { createPage } = actions
createPage({ path: "/custom/", component: require.resolve("./src/templates/custom.js") })
}
vuepress 配置相对集中。
- 通过
config.ts配置主题、插件和 Markdown 行为。 - 支持自定义主题和布局槽位。
- 适合需要定制文档样式的团队。
// vuepress: 配置文件
// docs/.vuepress/config.ts
export default {
title: "My Docs",
themeConfig: { nav: [{ text: "Home", link: "/" }] }
}
vitepress 配置极简。
- 通过
vitepress.config.ts配置。 - 鼓励使用默认主题，自定义能力弱于
vuepress。 - 适合快速启动，不需要深度定制的场景。
// vitepress: 极简配置
// docs/.vitepress/config.ts
export default {
title: "VitePress",
themeConfig: { nav: [{ text: "Home", link: "/" }] }
}
🚀 构建性能与开发体验：重量级 vs 轻量级
gatsby 构建速度较慢，尤其是数据量大时。
- GraphQL 架构在大规模数据下会有性能瓶颈。
- 热更新（HMR）速度取决于项目复杂度。
- 适合对构建时间不敏感的大型内容站。
// gatsby: 构建命令
// 通常较慢，尤其是首次构建
npm run build
// 输出：Building production JavaScript and CSS bundles...
vuepress 性能中等。
- v2 版本引入 Vite 后有所改善。
- 但仍保留了许多通用 SSG 的功能，包体积较大。
- 适合中型文档站。
// vuepress: 构建命令
// 速度适中
npm run docs:build
// 输出：Wait for fetching static resources...
vitepress 构建速度极快。
- 基于 Vite，利用原生 ES 模块。
- 冷启动和热更新几乎是瞬时的。
- 适合大型文档库或频繁更新的场景。
// vitepress: 构建命令
// 非常快
npm run docs:build
// 输出：build complete in 1.2s
📊 总结对比表
| 特性 | gatsby | vuepress | vitepress |
|---|---|---|---|
| 核心框架 | ⚛️ React | 🟢 Vue 2/3 | 🟢 Vue 3 |
| 构建工具 | 📦 Webpack | 📦 Webpack/Vite | ⚡ Vite |
| 数据层 | 🔗 GraphQL | 📝 Frontmatter | 📝 Frontmatter + JS |
| 主要用途 | 🌐 通用网站/电商 | 📚 定制文档站 | 📚 快速文档站 |
| 构建速度 | 🐢 较慢 | 🐇 中等 | 🚀 极快 |
| 配置复杂度 | 🔧 高 | 🔧 中 | 🔧 低 |
| 维护状态 | ✅ 活跃 | ✅ v2 活跃 (v1 已停更) | ✅ 活跃 |
💡 最终建议
gatsby 就像一辆重型卡车 🚛 — 功能强大，能装载复杂的数据货物，适合构建企业级营销站、电商平台或需要聚合多数据源的大型应用。但如果你只是需要一个小博客，它可能过于笨重。
vuepress 就像一辆定制房车 🚐 — 基于 Vue，适合需要深度定制文档主题和功能的团队。如果你发现 vitepress 的限制太多，vuepress v2 是更好的选择。
vitepress 就像一辆跑车 🏎️ — 极速、轻量、专注。它是编写 Vue 相关文档的首选，也是大多数技术文档的最佳选择。除非你有特殊的定制需求，否则优先选它。
核心决策点：
- 技术栈：React 团队选
gatsby，Vue 团队选vitepress或vuepress。 - 内容类型：通用网站选
gatsby，纯文档选vitepress。 - 性能要求：追求极致构建速度选
vitepress。 - 注意：避免在新项目中使用
vuepressv1，它已处于维护模式，请直接使用 v2 或vitepress。
如何选择: gatsby vs vitepress vs vuepress
- gatsby:
如果你的团队主要使用 React，并且项目需要聚合多个数据源（如 CMS、API、本地文件），
gatsby是最佳选择。它的 GraphQL 数据层能统一处理复杂数据，但构建速度较慢，适合内容密集型营销网站或大型电商平台。 - vitepress:
如果你需要为 Vue 项目编写文档，或者追求极致的构建速度和简洁的开发体验，选择
vitepress。它是 Vue 官方推荐的文档工具，配置简单，默认主题美观，但不适合需要高度自定义布局的复杂应用。 - vuepress:
如果你需要基于 Vue 构建文档站，但
vitepress的功能无法满足需求（如需要复杂的自定义布局或插件系统），则选择vuepressv2。它比vitepress更灵活，但构建性能稍弱，适合需要深度定制的技术文档站。
热门对比
gatsby的README
Gatsby
The future of web development is here.
Gatsby is a free and open source framework based on React that helps developers build blazing fast websites and apps.
It combines the control and scalability of dynamically rendered sites with the speed of static-site generation, creating a whole new web of possibilities.
Quickstart
·
Tutorial
·
Plugins
·
Starters
·
Showcase
·
Contribute
Support: Discussions
Gatsby helps professional developers efficiently create maintainable, highly-performant, content-rich websites.
-
Load Data From Anywhere. Gatsby pulls in data from any data source, whether it’s Markdown files, a headless CMS like Contentful or WordPress, or a REST or GraphQL API. Use source plugins to load your data, then develop using Gatsby’s uniform GraphQL interface.
-
Go Beyond Static Websites. Get all the benefits of static websites with none of the limitations. Gatsby sites are fully functional React apps, so you can create high-quality, dynamic web apps, from blogs to e-commerce sites to user dashboards.
-
Choose your Rendering Options. You can choose alternative rendering options, namely Deferred Static Generation (DSG) and Server-Side Rendering (SSR), in addition to Static Site Generation (SSG) — on a per-page basis. This type of granular control allows you to optimize for performance and productivity without sacrificing one for the other.
-
Performance Is Baked In. Ace your performance audits by default. Gatsby automates code splitting, image optimization, inlining critical styles, lazy-loading, prefetching resources, and more to ensure your site is fast — no manual tuning required.
-
Use a Modern Stack for Every Site. No matter where the data comes from, Gatsby sites are built using React and GraphQL. Build a uniform workflow for you and your team, regardless of whether the data is coming from the same backend.
-
Host at Scale for Pennies. Gatsby sites don’t require servers, so you can host your entire site on a CDN for a fraction of the cost of a server-rendered site. Many Gatsby sites can be hosted entirely free on Gatsby Cloud and other similar services.
-
Use Gatsby's Centralized Data Layer Everywhere. With Gatsby's Valhalla Content Hub you can bring Gatsby's data layer to any project. Making it accessible via a unified GraphQL API for building content sites, eCommerce platforms, and both native and web applications.
Learn how to use Gatsby for your next project.
🚀 Ship your first Gatsby site in 5 Minutes
Click the link below to quickly try the workflow of developing, building, and deploying websites with Gatsby and Gatsby Cloud.
At the end of this process, you'll have
- a site working on Gatsby Cloud
- a new repository that is linked to that new site
- as you push changes to your new repository, Gatsby Cloud will automatically rebuild and redeploy your site!
💻 Get started with Gatsby locally in 5 Minutes
You can get a new Gatsby site up and running on your local dev environment in 5 minutes with these four steps:
-
Initialize a new project.
npm init gatsbyGive it the name "My Gatsby Site".
-
Start the site in
developmode.Next, move into your new site’s directory and start it up:
cd my-gatsby-site/ npm run develop -
Open the source code and start editing!
Your site is now running at
http://localhost:8000. Open themy-gatsby-sitedirectory in your code editor of choice and editsrc/pages/index.js. Save your changes, and the browser will update in real time!
At this point, you’ve got a fully functional Gatsby website. For additional information on how you can customize your Gatsby site, see our plugins and the official tutorial.
🎓 Learning Gatsby
Full documentation for Gatsby lives on the website.
-
For most developers, we recommend starting with our in-depth tutorial for creating a site with Gatsby. It starts with zero assumptions about your level of ability and walks through every step of the process.
-
To dive straight into code samples head to our documentation. In particular, check out the “How-to Guides”, “Reference”, and “Conceptual Guides” sections in the sidebar.
We welcome suggestions for improving our docs. See the “how to contribute” documentation for more details.
Start Learning Gatsby: Follow the Tutorial · Read the Docs
🚢 Release Notes
Wondering what we've shipped recently? Check out our release notes for key highlights, performance improvements, new features, and notable bugfixes.
Also, read our documentation on version support to understand our plans for each version of Gatsby.
💼 Migration Guides
Already have a Gatsby site? These handy guides will help you add the improvements of Gatsby v5 to your site without starting from scratch!
❗ Code of Conduct
Gatsby is dedicated to building a welcoming, diverse, safe community. We expect everyone participating in the Gatsby community to abide by our Code of Conduct. Please read it. Please follow it. In the Gatsby community, we work hard to build each other up and create amazing things together. 💪💜
🤝 How to Contribute
Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Gatsby community!
Check out our Contributing Guide for ideas on contributing and setup steps for getting our repositories up and running on your local machine.
A note on how this repository is organized
This repository is a monorepo managed using Lerna. This means there are multiple packages managed in this codebase, even though we publish them to NPM as separate packages.
📝 License
Licensed under the MIT License.
💜 Thanks
Thanks go out to all our many contributors creating plugins, starters, videos, and blog posts. And a special appreciation for our community members helping with issues and PRs, or answering questions on GitHub Discussions.
A big part of what makes Gatsby great is each and every one of you in the community. Your contributions enrich the Gatsby experience and make it better every day.