Skip to Content
MUZINET-NOTE 4.0 is released 🎉
技术知识库React命名规范

🧩 命名规范（Naming Convention）

为保证项目结构清晰、可维护性高、URL 友好且符合 SEO 要求，
本文档定义了 MUZINET 文档项目的统一命名规则。

📁 文件夹命名规范（Folder Naming）

规则说明示例
使用 kebab-case（小写 + 中划线）所有目录名均使用小写字母和中划线连接✅ getting-started/
禁止使用大写字母URL 区分大小写，不统一会导致混乱❌ GettingStarted/
不使用下划线或空格_ 与空格会影响路径与 SEO❌ api_docs/, user guide/
不使用中文或特殊符号防止构建或路由出错❌ 接口文档/
建议层级不超过 3 层层级过深影响阅读和维护✅ guide/configuration/advanced/
排序推荐使用 _meta.json控制显示顺序与标题✅ _meta.json → { "installation": "安装" }
隐藏目录可用 _ 前缀不参与页面生成_components/, _drafts/

结构示例


docs/
├── getting-started/
│   ├── index.mdx
│   ├── installation.mdx
│   └── configuration.mdx
├── api-reference/
│   ├── overview.mdx
│   ├── authentication.mdx
│   └── endpoints.mdx
└── faq/
└── index.mdx

对应 URL：


/docs/getting-started
/docs/api-reference
/docs/faq

📝 文件命名规范（MDX File Naming）

规则说明示例
使用 kebab-case全小写 + 中划线连接✅ getting-started.mdx
禁止使用大写或下划线保持一致性与 SEO 友好❌ UserGuide.mdx, user_guide.mdx
禁止使用空格或特殊字符避免 URL 编码问题❌ API Reference.mdx
文件名使用英文确保路径兼容性✅ configuration-options.mdx
版本区分使用文件夹不在文件名中添加版本号✅ v1/guide.mdx
排序建议使用 _meta.json可控顺序，替代数字前缀✅ { "index": "介绍" }

文件结构示例


getting-started.mdx
api-reference.mdx
configuration-options.mdx
release-notes/2025-10-13-v1.2.0.mdx

_meta.json 示例

{
  "index": "介绍",
  "installation": "安装",
  "configuration": "配置"
}

⚛️ 组件命名规范（Component Naming）

规则说明示例
使用 PascalCase（帕斯卡命名）每个单词首字母大写✅ ButtonPrimary, HeroSection
名称语义化反映组件用途和作用✅ DocsSidebar, SearchInput
避免缩写代码可读性更高✅ UserAvatar, ❌ UsrAvt
每个组件单独文件夹避免命名冲突✅ /components/Button/Button.tsx
使用 index.ts 导出提高导入简洁性✅ export * from './Button'
样式文件同名方便查找与复用✅ Button.module.css
共享组件放在 _components/ 下避免与业务组件混淆_components/Alert/Alert.tsx

组件结构示例

components/
├── Button/
│   ├── Button.tsx
│   ├── Button.module.css
│   └── index.ts
├── HeroSection/
│   ├── HeroSection.tsx
│   ├── HeroSection.module.css
│   └── index.ts
└── _shared/
    ├── Alert/
    │   ├── Alert.tsx
    │   └── index.ts

✅ 总结检查表（Checklist）

类别命名方式示例
文件夹kebab-caseapi-reference/
文件kebab-case + .mdxgetting-started.mdx
组件PascalCaseUserProfileCard.tsx
排序_meta.json{ "index": "介绍" }
隐藏目录_ 前缀_drafts/

💡 补充说明

  • 统一命名能提升 项目可维护性 与 SEO 效果。
  • _meta.json 可定义标题与排序，替代文件名前缀。
  • 避免频繁修改已有路径，以防内部链接失效。
  • 本规范已在 MUZINET 官方文档结构 中实践使用。

🧱 最终示例

docs/
├── getting-started/
│   ├── index.mdx
│   ├── installation.mdx
│   └── configuration.mdx
├── api-reference/
│   ├── overview.mdx
│   ├── authentication.mdx
│   └── endpoints.mdx
└── components/
    ├── Button/
    │   ├── Button.tsx
    │   ├── Button.module.css
    │   └── index.ts
    └── Alert/
        ├── Alert.tsx
        └── index.ts
访问路径示例 → /docs/getting-started  
组件导入示例 → import { Button } from '@/components/Button'

🧠 提示：命名保持简单、语义化、统一英文， 是优秀文档与组件体系的第一步。

OIDC-ALL