在配置、审查或排查 Rspress v2…

适用于配置、审查或排查 Rspress v2 站点，帮助统一内容约定、导航、MDX、资源、搜索和部署做法。

适用场景

解决思路

1. 在 rspress.config.ts 中使用从 @rspress/core 导入的 defineConfig。
2. 当文档不在默认的 docs/ 目录下时，显式设置 root。
3. 将 title、description、icon、logo、base、lang 等站点级设置保留在配置中，不要在页面文件里重复。
4. 优先使用 Rspress 一等配置选项，再考虑自定义主题代码或低层打包器覆盖。
5. 将自定义主题代码放在顶层 theme/ 目录，并从 @rspress/core/theme-original 导入原始主题片段。
6. 本地开发使用 rspress dev。
7. 生产输出使用 rspress build。
8. 仅在本地预览构建产物时使用 rspress preview。
9. 仅当 CSS 变量、类覆盖或布局包裹无法解决定制需求时，才使用 rspress eject。
10. 将文档内容放在一个清晰的 docs 根目录下，按主题或工作流分组页面，而不是按团队归属分组。
11. 使用 _meta.json 或 _nav.json 控制侧边栏和导航的标签/顺序，不要在文件名中编码顺序。
12. 将可复用的 MDX 片段或共享组件放在共享文件中，不要在各页面间复制。
13. 保持落地页简洁，并从中链接到更深入的面向任务的指南。
14. 添加清晰的 title 和 description frontmatter；仅当页面默认值不够用时才设置 sidebar、outline、navbar 或 footer。
15. 根据布局需要有意使用 pageType: home、doc、doc-wide、custom 或 blank。
16. 编写任务优先的标题和简短介绍；技术文档中避免营销式文案。
17. 优先一页一个主题，并按工作流或功能领域拆分过长页面。
18. 保持代码示例最小、可运行且版本准确。
19. 使用 MDX 实现交互式文档和嵌入组件，但主叙述应保持为可理解的普通 Markdown。
20. 优先使用有文档的 Rspress 主题/运行时 API，不要从内部源码路径导入。
21. 对于应用级 UI 或 providers，使用 globalUIComponents 或主题覆盖，而不是在每个页面重复导入。
22. 优先使用 CSS 变量设置品牌色、间距和表面样式。
23. 优先使用 BEM 类覆盖或 Layout slots，再考虑 eject 内置组件。
24. 在 theme/ 文件中保留 export * from '@rspress/core/theme-original'，除非有意替换某个具名导出。
25. 除非配置、CSS 和包裹都无法满足需求，否则避免完整 eject 组件。
26. 多语言站点将各语言内容组织在按语言划分的目录下，并在可行时保持导航镜像。
27. 保持 description 及其他 frontmatter 文本与页面内容使用同一种语言。
28. 有意识地配置搜索：中小型站点使用本地搜索，规模或跨版本索引需要时使用托管搜索。
29. 仅当站点受益于机器可读输出时启用 llms 或 ssgMd；由于这些输出会呈现页面摘要，需保持 description 准确。
30. 当图片和组件属于内容时，从 docs/theme 源中导入由源码管理的图片和组件。
31. 仅将 public/ 用于必须保持稳定 URL 路径的资源，例如 favicons、社交图片或下载文件。
32. 通过绝对站点路径引用 public 资源，并确保设置 base 后仍能正常工作。
33. 在构建自定义方案前，搜索、预览和 API 文档场景优先使用官方 Rspress 插件。
34. 组件或库文档需要交互式演示或 API 表格时，使用 @rspress/plugin-preview 和 @rspress/plugin-api-docgen。
35. 在配置中显式保留插件使用情况，并移除未使用的插件以降低维护成本。
36. 同时验证 rspress dev 和 rspress build；在 dev 中正常的页面仍可能在静态生成时失败。
37. 部署前验证失效链接、缺失资源和错误的 base 处理。
38. 除非托管工作流明确要求提交构建产物，否则不要将生成输出纳入源码控制。
39. 调试内容问题时，先检查解析后的 docs 根目录、frontmatter 和主题覆盖，再假定是打包器问题。
40. 要获取最新 Rspress 文档，请阅读 https://rspress.rs/llms.txt。
41. 检查确切选项名称或当前行为时，使用配置和 API 文档。

适用边界 · 注意事项

• 不适用于非 Rspress 站点或 Rspress v1 项目。
• 如果只是临时、简单的 Markdown 页面，且不需要 Rspress 的导航、搜索、主题或插件能力，无需套用这些实践。
• 如果项目强依赖自定义打包器或主题，且无法迁移到 Rspress 一等选项，不宜强行套用。