Hexo 博客构建实战从 Hello World 文章到静态站点生成与部署【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel本文以 Vercel 开源仓库中的 Hexo v6 测试夹具fixture为核心样本深入拆解一篇标准 Hexo 博客文章的完整生命周期从hello-world.md的 front-matter 与 Markdown 正文结构到hexo new / server / generate / deploy四大命令的工作流再到_config.yml站点配置、package.json脚本依赖以及 Vercel 如何自动识别 Hexo 框架并执行构建与探测验证。读完本文你将掌握 Hexo 博客从零写作、本地预览、静态生成到云端部署的完整技术链路。一、样本定位这是 Vercel 仓库中的 Hexo v6 构建测试样本本篇文章所基于的关联文档是 hello-world.md它位于 Vercel 仓库packages/static-build的集成测试夹具目录中是用于验证「Hexo v6 站点能否被正确构建」的最小博客样本。与其配套的完整夹具目录结构如下packages/static-build/test/fixtures/hexo-v6/ ├── scaffolds/ │ ├── draft.md # 草稿模板 │ ├── page.md # 独立页面模板 │ └── post.md # 文章模板 ├── source/ │ └── _posts/ │ └── hello-world.md # 默认首篇文章本文主体 ├── themes/ # 主题目录v6 样本中留空 ├── _config.landscape.yml # landscape 主题配置 ├── _config.yml # 站点全局配置 ├── package-lock.json ├── package.json # 依赖与脚本 └── probes.json # 构建后的探测断言仓库中同时保留了 hexo-v5 夹具两套样本分别对应 Hexo 5.x 与 6.x 两个大版本用于回归验证不同版本下的构建兼容性。本文以 v6 样本为主线兼顾 v5 差异对比。二、读懂 hello-world.mdfront-matter 与 Markdown 正文hello-world.md全文只有 38 行却完整展示了一篇 Hexo 文章的两种核心组成YAML front-matter 元数据与Markdown 正文。2.1 front-matter文章的元数据头文件开头以---分隔的区块即为 front-matterHexo 用它来声明文章的元信息--- title: Hello World ---title文章标题会被渲染为页面h1及浏览器标签页标题除title外Hexo 还支持date写作日期、tags标签、categories分类、permalink自定义链接等常用元数据字段。可对照仓库中的文章模板 scaffolds/post.md 看到新文章自动生成的元数据骨架--- title: {{ title }} date: {{ date }} tags: ---当执行hexo new创建新文章时Hexo 会基于该模板填充变量生成带title、date和空tags列表的新文件。这也是为什么 hello-world.md 中只显式写了title——它由脚手架生成后作者手动补充了正文。2.2 正文标准 Markdown 渲染front-matter 之后即正文。hello-world.md 正文使用标准 Markdown 编写Welcome to Hexo! This is your very first post. ... ## Quick Start ### Create a new post $ hexo new My New Post ### Run server $ hexo server ### Generate static files $ hexo generate ### Deploy to remote sites $ hexo deploy这些内容本身即是 Hexo 官方的「快速开始」指引涵盖写作、预览、生成、部署四个环节。渲染时##生成二级标题、###生成三级标题代码块会被 highlight 配置 处理为带行号的语法高亮。三、Hexo 四步工作流new / server / generate / deployhello-world.md 正文中浓缩了 Hexo 的核心命令行工作流本节逐一展开并补充 Vercel 场景下的实际用法。3.1 创建新文章hexo new$ hexo new My New Post命令依据 scaffolds/post.md 模板在source/_posts/下生成My-New-Post.md新文章的文件名格式由_config.yml中的new_post_name: :title.md决定即默认使用标题作为文件名若以draft作为布局如hexo new draft title则使用 scaffolds/draft.md 模板且默认不被渲染render_drafts: false。3.2 本地预览hexo server$ hexo server启动内置开发服务器依赖hexo-server包默认监听4000端口支持热重载在 Vercel 开发环境vercel dev中框架定义的开发命令为hexo server --port $PORT见下文框架检测一节由平台动态注入端口生成的静态文件默认输出到_config.yml的public_dir指定目录默认public。3.3 生成静态文件hexo generate$ hexo generate这是构建的核心命令将source/下的所有 Markdown 渲染为 HTML并拷贝主题静态资源到public/目录在 Vercel 部署中该命令即默认的 Build Commandframeworks.ts中的value: hexo generate常用简写为hexo g生产环境建议配合hexo clean先清理缓存。3.4 部署到远程站点hexo deploy$ hexo deploy通过_config.yml的deploy段配置 Git 仓库、Rsync 或 FTP 等部署目标在 Vercel 平台上这一步并非必需——平台直接消费hexo generate产出的public/目录构建结果上传到云端静态托管与 CDN无需配置deploy段样本中deploy.type即为空。四、逐项拆解 _config.yml一个可运行的 Hexo 6 站点配置hexo-v6/_config.yml 是一份完整可运行的 Hexo 6 配置覆盖站点信息、URL、目录、写作、分页、主题等全部区块本节按功能分组逐项解读。4.1 站点信息Sitetitle: Hexo subtitle: description: keywords: author: John Doe language: en timezone: title/subtitle/description分别渲染到页面标题、副标题和meta namedescriptionlanguage站点语言影响 i18n 与主题文案timezone留空表示使用服务器时区文章日期按此解析。4.2 URL 与永久链接URLurl: http://example.com permalink: :year/:month/:day/:title/ permalink_defaults: pretty_urls: trailing_index: true # 置 false 可移除 permalink 中的 index.html trailing_html: true # 置 false 可移除 permalink 中的 .htmlpermalink决定文章 URL 结构:year/:month/:day/:title/是默认的日期层级式永久链接pretty_urls控制 URL 美化关闭trailing_html后xxx/index.html会变成xxx/。4.3 目录结构Directorysource_dir: source public_dir: public tag_dir: tags archive_dir: archives category_dir: categories code_dir: downloads/code i18n_dir: :lang skip_render:source_dirMarkdown 源文件目录hello-world.md就位于其_posts/子目录public_dir构建输出目录Vercel 的 Output Directory 正是指向这里frameworks.ts中outputDirectory.value: publicarchive_dir/tag_dir/category_dir分别对应归档页、标签页、分类页的路由前缀测试样本的probes.json就验证了/archives归档页的存在。4.4 写作与渲染Writingnew_post_name: :title.md # 新文章文件名格式 default_layout: post titlecase: false external_link: enable: true # 外部链接在新标签页打开 field: site highlight: enable: true # 代码高亮开关 line_number: true wrap: true prismjs: enable: falsehighlight区块控制内置的代码高亮器正文中所有代码块如hexo new等命令示例默认启用行号显示prismjs是替代方案样本中关闭。4.5 首页与分页Home / Paginationindex_generator: path: per_page: 10 # 每页 10 篇文章 order_by: -date # 按日期倒序 per_page: 10 pagination_dir: page首页生成器按日期倒序排列文章每页 10 篇多余页面以/page/2/形式分页。4.6 主题Themetheme: landscapev6 样本的主题目录themes/为空但package.json声明了hexo-theme-landscape: ^1.0.0npm 依赖因此主题实际以 npm 包形式安装_config.landscape.yml则为该主题提供站点级覆盖配置。五、package.json脚本、依赖与版本差异hexo-v6/package.json 定义了站点的依赖与命令脚本{ name: hexo-site, scripts: { build: hexo generate, clean: hexo clean, deploy: hexo deploy, server: hexo server }, dependencies: { hexo: ^6.3.0, hexo-generator-archive: ^2.0.0, hexo-generator-category: ^2.0.0, hexo-generator-index: ^3.0.0, hexo-generator-tag: ^2.0.0, hexo-renderer-ejs: ^2.0.0, hexo-renderer-marked: ^6.0.0, hexo-renderer-stylus: ^3.0.0, hexo-server: ^3.0.0, hexo-theme-landscape: ^1.0.0 } }hexo主框架v6.3.0自带 CLI提供hexo new/server/generate/deploy全部命令hexo-generator-*系列分别负责归档、分类、首页、标签四个页面的生成probes.json探测的/archives正是由hexo-generator-archive产出hexo-renderer-marked负责 Markdown → HTML 渲染hexo-renderer-ejs与hexo-renderer-stylus服务于主题模板landscape 主题基于 EJS Stylushexo-server提供本地预览服务器在 Vercel 构建时平台会执行npm install安装上述依赖然后运行npm run build即hexo generate。与 hexo-v5/package.json 对比v5 夹具使用hexo ^5.3.0及对应版本的生成器与渲染器v6 则整体升级到 6.x 世代如hexo-renderer-marked从 ^3.x 升到 ^6.x、hexo-renderer-stylus从 ^2.x 升到 ^3.x。两套夹具并存用于验证 Vercel 静态构建流水线对新旧两个大版本 Hexo 的兼容性。六、Vercel 如何识别并构建 Hexo 站点6.1 框架检测与默认参数在 packages/frameworks/src/frameworks.ts 中定义了 Hexo 框架的完整元数据{ name: Hexo, slug: hexo, detectors: { every: [{ matchPackage: hexo }], // 检测到 hexo 依赖即命中 }, settings: { installCommand: { placeholder: yarn install, pnpm install, npm install, or bun install }, buildCommand: { placeholder: npm run build or hexo generate, value: hexo generate, // 默认构建命令 }, devCommand: { value: hexo server --port $PORT, // 开发命令端口由平台注入 placeholder: hexo server, }, outputDirectory: { value: public }, // 构建输出目录 }, dependency: hexo, getOutputDirName: async () public, }关键结论检测机制Vercel 通过detectors.every.matchPackage: hexo规则在项目根package.json的 dependencies 中检测到hexo包即判定为 Hexo 项目样本 package.json 完全满足该条件构建命令默认执行hexo generate将 Markdown 渲染为静态 HTML 输出到public/输出目录public即_config.yml中public_dir的默认值开发命令本地vercel dev时运行hexo server --port $PORT端口由 Vercel 动态分配避免与本地其他服务冲突。6.2 构建后的验证probes.json构建完成后probes.json 定义了自动化探测断言用于验证静态产物是否符合预期{ probes: [ { path: /, mustContain: Hello World }, { path: /, mustContain: Hexo }, { path: /archives, mustContain: Hello World } ] }请求首页/响应 HTML 必须包含Hello World与Hexo——前者验证文章正文被正确渲染标题来自 front-matter 的title字段后者验证站点标题_config.yml的title: Hexo注入页面请求归档页/archives同样必须包含Hello World验证hexo-generator-archive正常生成了归档索引页。这套断言直接印证了 hello-world.md 中 front-matter 与正文、_config.yml站点配置、归档生成器三者之间的数据流转元数据决定标题渲染正文决定页面内容归档生成器把文章收录进归档索引。七、将 Hexo 站点接入 Vercel 的推荐步骤综合以上分析一个标准的 Hexo 站点接入 Vercel 部署的完整流程为本地初始化安装hexo并执行hexo init生成站点骨架目录结构与本样本一致写作执行hexo new My New Post在source/_posts/下基于 post.md 模板编辑文章本地预览hexo server在 4000 端口预览效果提交构建将项目推送到 Git 仓库并导入 Vercel平台自动检测hexo依赖、以hexo generate作为构建命令、以public作为输出目录验证发布构建完成后访问线上地址检查首页标题、文章内容与归档页对应probes.json的三条断言是否正常。八、小结本文以 hello-world.md 这一最小样本为起点串联起 Hexo 站点的完整技术链路front-matter 定义文章元数据、Markdown 定义正文内容、hexo generate完成静态渲染、_config.yml控制站点全局行为、package.json声明依赖与脚本。在 Vercel 生态中平台通过 frameworks.ts 的检测规则自动识别 Hexo以hexo generate为构建命令、public为输出目录完成云端构建再由probes.json对产物进行内容级验证。掌握这条链路后无论是用 Hexo 搭建个人博客还是为 Hexo 插件、主题编写自动化构建测试都能快速定位配置入口与构建行为。【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考