Ente 帮助文档站实战指南：基于 VitePress 的本地预览、构建与内容贡献

本文以 Ente 官方帮助文档站点（仓库 docs/ 目录）为对象，讲解这套承载 Ente Photos、Ente Auth、Ente Locker 等产品帮助内容的文档系统如何在本机运行预览、构建发布，以及贡献者如何以最小成本参与文档编辑。读完本文，你将掌握 npm ci / npm run dev / npm run build 的完整开发流程、文档目录的内容组织方式，以及官方文档的写作规范与提交约定。

文档站概述：docs 目录在仓库中的角色

在 Ente 这个庞大的 monorepo 中，docs/ 目录是产品帮助文档的独立站点。官方说明（docs/README.md）指出，这些文档为 Ente 的全部产品提供帮助与使用说明，其线上版本发布在 ente.com/help，并且线上站点会在 PR 合并后的几分钟内自动更新——这意味着任何人提交的文档改动都会快速上线，参与门槛极低。

整个文档站基于 VitePress 构建。这一点可以从 docs/package.json 的依赖声明确认：vitepress: 1.6.4 是唯一的文档站点框架依赖，另有 prettier: 3.8.3 负责代码与文本格式校验、sitemap: 9.0.1 用于站点地图生成，包管理器为 npm@11.12.1。

从内容结构看，docs/docs/ 目录下按产品与主题划分了清晰的栏目：

• photos/：Ente Photos 的用户指南，包含 getting-started、features、faq、migration、troubleshooting 等子目录；
• auth/：Ente Auth（2FA 认证器）的指南与 FAQ；
• locker/：Ente Locker 安全存储的文档；
• self-hosting/：自托管部署相关的安装、管理与维护文档；
• 另有 2of3、cli、de、ensu、paste、qr、public（静态资源）等栏目。

文档站首页由 docs/docs/index.md 承载，它介绍了 Ente 平台定位（端到端加密、隐私、可靠地在云端存储数据）、三个核心应用（Ente Photos / Ente Auth / Ente Locker）以及社区与支持渠道。

本地运行：三行命令启动文档预览

对于任何需要改动内容的场景，官方推荐的流程是先在本地跑起预览，避免盲改。完整步骤如下（docs/README.md）：

git clone https://gitcode.com/GitHub_Trending/en/ente
cd ente/docs
npm ci
npm run dev

逐条解读：

• git clone 将整个 Ente 仓库克隆到本地，docs 文档站包含在 monorepo 内，无需单独克隆；
• cd ente/docs 进入文档站的工作目录；
• npm ci 依据 docs/package-lock.json 精确安装锁定版本的依赖。根据 docs/CLAUDE.md 的约定，应优先使用 npm ci，只有在主动新增或升级依赖、或 package-lock.json 自上次 npm ci 后有变动时，才使用 npm install；
• npm run dev 启动 VitePress 开发服务器，本地实时预览文档，改动保存后页面热更新。

执行 npm run dev 后，VitePress 默认在 http://localhost:5173 提供服务（具体端口以启动输出为准），浏览器打开即可看到与线上 ente.com/help 结构一致的帮助站点。

开发命令全景：从开发到生产构建

docs/package.json 中定义了文档站的全部 npm scripts，是理解整个开发流程的钥匙：

命令	对应脚本	用途
npm run dev	vitepress dev docs	启动本地开发服务器，用于日常编辑与实时预览
npm run build	vitepress build docs	构建生产版本，输出静态站点文件
npm run preview	vitepress preview docs	本地预览生产构建产物，验证最终效果
npm run lint	prettier --check --log-level warn .	全站格式检查（只检查不修改）
npm run lint:fix	prettier --write --log-level warn .	全站格式检查并自动修复

值得注意的细节：所有 VitePress 命令都显式传入了 docs 参数，说明 VitePress 的源目录被刻意命名为 docs，形成了 docs/docs/ 这一目录嵌套。构建前通常建议先跑 npm run lint 保证格式统一，避免 CI 或 PR 检查失败。

快速编辑：面向微小修复的贡献路径

docs/README.md 给出了"Quick edits"的轻量贡献方式：对于拼写错误或小型修复，无需在本地搭环境，直接在 GitHub 上编辑对应文件并提交 Pull Request 即可。这是官方为低门槛贡献者设计的路径——因为线上站点在 PR 合并后数分钟内即更新，一个小修复几分钟后就会生效。

如果想要快速定位待修改的内容，可以从各栏目索引页入手，例如 docs/docs/photos/index.md 列出了 Photos 帮助文档的四个分区（Getting Started、Features、FAQ、Troubleshooting）以及 Discord、邮件、GitHub 等支持渠道，changelog.md 则记录了近期变更。

文档写作规范与提交约定

文档站的开发规范集中记录在 docs/CLAUDE.md 中，参与贡献前务必阅读：

命令约定

npm ci          # 安装依赖
npm run dev     # 启动本地开发服务器
npm run build   # 构建生产版本

提交信息：保持简短，一行内完成（除非有特殊要求）；禁用 emoji、推广性文字或链接、以及 Co-Authored-By 行。

侧边栏：VitePress 不会自动生成侧边栏，新增页面必须手工添加到 docs/.vitepress/sidebar.ts。这是新手最容易遗漏的一步——新写页面若不注册到侧边栏，将不会出现在站点导航中。

写作风格要点（完整版见 docs/docs/photos/STYLE_GUIDE.md）：

• 使用祈使句语气，例如写"Open Settings"而非"You can open Settings"；
• 导航动作统一用 "Open"，不要用 "Go to" 或 "Navigate to"；
• 移动端用 "Tap"，桌面端与网页端用 "Click"；
• 设置路径使用代码格式与 > 分隔，例如 `Settings > Backup > Folders`；
• 平台说明使用加粗标题，如 **On mobile:**、**On desktop:**、**On web:**、**On iOS:**；
• FAQ 问题必须使用唯一的描述性锚点 ID，如 ### Question? {#enable-face-recognition-ml}，且需保证全站唯一，可用 grep 检查重复；
• 链接引导语统一使用 "Learn more"。

从文档到产品：docs 与仓库其他部分的关联

文档站虽然是独立的 VitePress 项目，但内容与仓库其他模块紧密对应。例如 docs/docs/self-hosting/ 中的安装手册与 server/、web/、cli/ 等目录的实际部署方式一一对应；docs/docs/auth/ 的 2FA 功能说明与 mobile/apps/auth/（Flutter 客户端）及 cli/ 中的 ente auth 命令实现相互印证。当你在文档中看到某个功能描述时，都可以在仓库对应子目录中找到其真实实现，这为文档审校提供了可靠的交叉验证途径。

小结

Ente 帮助文档站是一个基于 VitePress 1.6.4 构建、随 monorepo 一并维护的独立站点。它通过 npm ci + npm run dev 即可在本地完整复现线上帮助中心，通过 npm run build 产出可部署的静态站点；配合"Quick edits"路径与 docs/CLAUDE.md 中明确的格式规范、侧边栏注册约定与提交信息要求，任何开发者都能以极低成本参与 Ente 官方文档的维护。