front-end-interview-handbook 官网构建实战：基于 Docusaurus 与 vite-plus 的本地开发、构建与部署全流程

本文以 website/README.md 为核心，完整讲解 front-end-interview-handbook 官方文档站的工程化构建流程：从仓库根目录一键安装依赖，到启动带热更新的本地开发服务器，再到生成静态产物并推送部署。读完本文，你可以独立在本地跑起整套文档站，理解 vp（vite-plus）命令背后实际触发了哪些 Docusaurus 脚本，并能基于 website/docusaurus.config.js 的定位、国际化与重定向配置进行扩展维护。

一、仓库中的官网是什么

front-end-interview-handbook 是一份前端面试准备资料库，其在线阅读载体 frontendinterviewhandbook.com 由仓库内的 website/ 目录承载，是一个典型的 Docusaurus 静态站点工程：

• website/contents/：Markdown 格式的文档正文（面试指南、算法题、CSS/HTML/JavaScript 问题集、各公司面试题等），其中 routeBasePath 配置为 /，即文档直接挂在站点根路径下；
• website/i18n/：简体中文、日语、韩语等 10 种语言的翻译内容，与 website/docusaurus.config.js 中 i18n.locales 声明的 en、zh-CN、es、ja-JP、kr、pl、pt-BR、ru、tl、bn 一一对应；
• website/src/：自定义主题组件（侧边广告位、首页、DocItem 布局、TOC 等）与 website/src/css/custom.css 样式覆盖；
• website/static/：直接随构建产出的静态资源，包括 website/static/CNAME（内容 frontendinterviewhandbook.com，用于 GitHub Pages 自定义域名）和 website/static/_redirects（旧路径到新路径的重写规则，例如 /algorithms → /coding/algorithms/）。

需要说明一个版本事实：website/README.md 原文写的是 "built using Docusaurus 2"，但从 website/package.json 的实际依赖清单看，核心包已固定为 Docusaurus 3.1.1（@docusaurus/core、@docusaurus/preset-classic、@docusaurus/plugin-client-redirects 均为 3.1.1，配合 React 18.2.0）。因此阅读旧文档描述时，应以依赖清单声明的 3.1.1 为运行时准。

二、pnpm Workspace 与 vp CLI：命令是怎么串起来的

本仓库是一个 pnpm monorepo，pnpm-workspace.yaml 声明了唯一的 workspace 包 website，并维护了 vite、vitest、vite-plus 的 catalog 与 overrides。根 package.json 的关键事实：

• packageManager: pnpm@10.28.1，指定了包管理器版本；
• devDependencies 中包含 vite-plus（通过 catalog: 引用）、langnostic 及其 MDX 插件、TypeScript；
• scripts.prepare 为 vp config，即每次安装后 vite-plus 会自动完成自身的配置初始化。

website/README.md 中所有命令都以 vp 开头并要求"从仓库根目录执行"。这些命令并非直接调用 npm script，而是由 vite.config.ts 中的 run.tasks 配置转发到 website workspace 包内部的脚本。对照 website/package.json 的 scripts 字段，映射关系如下：

vp 命令（仓库根目录）	vite.config.ts 任务定义	实际执行的 website 脚本	底层 Docusaurus 命令
vp run dev	dev：vp run website#dev，cache: false	docusaurus start	开发服务器
vp run start	start：vp run website#start，cache: false	docusaurus start	开发服务器
vp run build	build：vp run website#build	docusaurus build	静态构建
vp run deploy	deploy：vp run website#deploy，dependsOn: ['build']，cache: false	docusaurus deploy	构建 + 推送 gh-pages
vp run i18n	i18n：vp exec langnostic translate	—	多语言翻译管线

另外 vite.config.ts 还配置了 staged（git pre-commit 时执行 vp check --fix）与 lint/format 规则，且 generatedIgnores 明确忽略 website/.docusaurus/** 与 website/build/**——从源码结构看，这两个目录正是 Docusaurus 开发期缓存与最终构建产物所在。

三、Installation：安装依赖

按 website/README.md 的说明，从仓库根目录执行：

vp install

该命令由 vite-plus 包装执行 workspace 的依赖安装。结合根 package.json 可知：

• 仓库锁定 pnpm 10.28.1（packageManager 字段），若本地 pnpm 版本不一致，建议先用 corepack 对齐版本再执行；
• 安装过程会自动触发 prepare: vp config，初始化 vite-plus 的运行时配置；
• 依赖范围覆盖根工具链（langnostic、vite-plus、TypeScript）与 website 包内的全部 Docusaurus 依赖。

四、Local Development：本地开发服务器

vp run dev

执行链路为 vp run dev → vite.config.ts 的 dev 任务 → vp run website#dev → website/package.json 的 "dev": "docusaurus start"。

按原文档描述，该命令启动本地开发服务器并自动打开浏览器窗口；得益于 Docusaurus 基于 Webpack 的开发服务器，绝大多数 Markdown 与配置修改都能即时热更新，无需重启服务器。几个实操要点：

• 开发服务器的端口若被占用，Docusaurus 会提示并顺延端口，以终端实际输出为准；
• 修改 website/docusaurus.config.js 中 navbar、footer、themeConfig 等配置即可调整站点导航与页脚；
• 修改 website/sidebars.js 可调整侧边栏结构——当前侧边栏按"Coding interview / Quiz/trivia / System design interview / Interview questions 🔥（30 家公司）"等分类组织 website/contents/ 下的全部文档，且 front-end-system-design 等分类使用 collapsed: false 默认展开；
• dev 任务设置了 cache: false，意味着该任务不会被 vite-plus 缓存，保证每次都是全新启动。

五、Build：生成静态产物

vp run build

对应链路 vp run build → vp run website#build → docusaurus build。按原文档描述，该命令将站点生成为静态内容并输出到 build 目录（即 website/build/），产物可以用任何静态内容托管服务提供访问。

结合仓库配置，构建产物中还会包含：

• website/static/CNAME：声明自定义域名 frontendinterviewhandbook.com，GitHub Pages 会据此响应该域名；
• website/static/_redirects：一组旧版 URL 到新路由的重写规则（如 /utility-function → /coding/javascript-utility-function/、/pop-quiz → /trivia/），用于兼容历史链接；
• website/docusaurus.config.js 中通过 @docusaurus/plugin-client-redirects 声明的客户端重定向（/en/css-questions → /css-questions 等），与静态 _redirects 文件构成"静态规则 + 客户端规则"双层重定向。

构建期还会受 sitemap.ignorePatterns 影响：若干博客标签页与文章被排除出 sitemap，避免搜索引擎收录低价值页面。

六、Deployment：部署到 GitHub Pages

GIT_USER=<Your GitHub username> USE_SSH=1 vp run deploy

按原文档说明：如果你使用 GitHub Pages 托管站点，该命令是一种便捷的"构建 + 推送"方式——它先构建网站，再把产物推送到 gh-pages 分支。结合 vite.config.ts 可以补充两点实现细节：

• deploy 任务声明了 dependsOn: ['build'] 且 cache: false，即部署前会强制执行一次干净的 build，避免推送过期产物；
• USE_SSH=1 让推送走 SSH 协议（需要本地已配置对应仓库的 SSH key），GIT_USER 则是 Docusaurus deploy 流程中识别 git 身份所需的环境变量；
• 若改用自定义托管（而非 GitHub Pages），则跳过 deploy，直接把 build 目录产物交给任意静态托管服务即可——这正是静态站点生成器的可移植性优势。

七、与多语言内容管线的衔接

官网文档只是整个仓库内容体系的一部分。从 langnostic.config.ts 可以看到，packages/ 下的 quiz、behavioral-interview-guidebook、front-end-interview-guidebook、react-interview-playbook、system-design 等 MDX 内容包，通过 langnostic（AI provider 配置为 google）以 en-US 为源语言生成 zh-CN 等目标语言文件；vp run i18n 任务（vp exec langnostic translate）就是这条管线的入口。理解这一点有助于区分两类多语言文件：website/i18n/ 下的 Docusaurus 翻译与 packages/ 下由 langnostic 生成的 {locale}.mdx。

八、常用操作速查

目标	命令（仓库根目录执行）	依据
安装依赖并初始化 vp 配置	vp install	website/README.md、根 package.json
本地开发（热更新）	vp run dev（等价 vp run start）	vite.config.ts、website/package.json
生成静态产物（website/build/）	vp run build	vite.config.ts
构建并推送 gh-pages 分支	GIT_USER=<user> USE_SSH=1 vp run deploy	website/README.md
运行多语言翻译管线	vp run i18n	vite.config.ts、langnostic.config.ts

适用前提小结：所有命令均以"仓库根目录 + pnpm 10.28.1 + 已安装 vite-plus"为前提；文档中 "Docusaurus 2" 的表述与依赖清单中的 3.1.1 存在出入，涉及具体 Docusaurus 行为时请以 3.1.1 为准。按上述流程，你可以完整复现官方文档站的开发、构建与部署链路。