MagiCMS 麦吉CMS

Appearance

开发指南 ​

开发环境搭建 ​

系统要求 ​

  • 操作系统: macOS / Windows / Linux
  • Node.js: >= 18.0.0
  • 包管理器: npm >= 9.0.0 或 pnpm >= 8.0.0
  • Git: >= 2.30.0

推荐工具 ​

  • IDE: VSCode / WebStorm
  • 浏览器: Chrome / Edge / Safari（最新版）

项目架构 ​

目录结构 ​

magicms/
├── apps/                    # 应用层
│   ├── admin/              # 管理后台
│   ├── web/                # 前台站点
│   └── mobile/             # 移动端应用
├── packages/               # 共享包
│   ├── sdk/                # CMS SDK
│   ├── ui/                 # UI 组件库
│   ├── shared/             # 共享工具
│   └── types/              # 类型定义
├── server/                 # 服务端
│   ├── api/                # API 服务
│   ├── render/             # SSR 渲染服务
│   └── scheduler/          # 定时任务服务
├── plugins/                # 插件目录
├── themes/                 # 主题目录
├── docs/                   # 文档
└── scripts/                # 脚本工具

开发规范 ​

代码规范 ​

  • 使用 ESLint + Prettier 进行代码格式化
  • 遵循 Vue 3 组合式 API 风格
  • TypeScript 严格模式启用
  • 组件命名使用 PascalCase
  • 函数命名使用 camelCase

Git 规范 ​

类型(scope): 简短描述

详细描述（可选）

Footer（可选）

类型说明：

  • feat: 新功能
  • fix: 修复
  • docs: 文档
  • style: 格式
  • refactor: 重构
  • perf: 性能优化
  • test: 测试
  • chore: 构建/工具

示例：

feat(content): 添加 AI 辅助写作功能

- 支持大纲生成
- 支持内容续写
- 支持文案润色

Closes #123

分支管理 ​

  • main: 主分支，稳定版本
  • develop: 开发分支
  • feature/*: 功能分支
  • hotfix/*: 紧急修复
  • release/*: 发布分支

模块开发 ​

内容模型开发 ​

typescript
// packages/sdk/src/models/article.ts
export interface ArticleModel {
  id: string
  title: string
  content: string
  summary?: string
  cover?: string
  category?: string
  tags?: string[]
  status: 'draft' | 'pending' | 'published' | 'archived'
  createdAt: Date
  updatedAt: Date
  publishedAt?: Date
}

export const articleModelConfig = {
  name: 'article',
  displayName: '文章',
  fields: [
    { name: 'title', type: 'text', required: true, label: '标题' },
    { name: 'content', type: 'richtext', required: true, label: '正文' },
    { name: 'summary', type: 'textarea', label: '摘要' },
    { name: 'cover', type: 'image', label: '封面图' },
    { name: 'category', type: 'relation', target: 'category', label: '分类' },
    { name: 'tags', type: 'relation', target: 'tag', multiple: true, label: '标签' }
  ]
}

主题开发 ​

typescript
// themes/default/index.ts
import { defineTheme } from '@magicms/sdk'

export default defineTheme({
  name: 'default',
  displayName: '默认主题',
  version: '1.0.0',
  templates: {
    index: './templates/index.vue',
    article: './templates/article.vue',
    category: './templates/category.vue',
    tag: './templates/tag.vue',
    search: './templates/search.vue'
  },
  config: {
    primaryColor: '#7C3AED',
    layout: 'sidebar',
    sidebarWidth: 280
  }
})

插件开发 ​

typescript
// plugins/my-plugin/index.ts
import { definePlugin } from '@magicms/sdk'

export default definePlugin({
  name: 'my-plugin',
  displayName: '我的插件',
  version: '1.0.0',
  description: '自定义插件示例',
  setup(cms) {
    // 注册自定义路由
    cms.router.addRoute({
      path: '/my-page',
      component: () => import('./views/MyPage.vue')
    })

    // 注册自定义内容模型
    cms.model.register({
      name: 'custom',
      displayName: '自定义内容',
      fields: [
        { name: 'title', type: 'text', required: true },
        { name: 'content', type: 'richtext' }
      ]
    })

    // 注册 AI 工具
    cms.ai.registerTool({
      name: 'my-tool',
      description: '自定义 AI 工具',
      handler: async (input) => {
        return { result: '处理完成' }
      }
    })
  }
})

页面开发 ​

vue
<!-- apps/admin/src/views/content/ArticleList.vue -->
<template>
  <div class="article-list">
    <PageHeader title="文章管理">
      <template #actions>
        <a-button type="primary" @click="handleCreate">
          新建文章
        </a-button>
      </template>
    </PageHeader>
    <ContentTable
      :columns="columns"
      :data-source="articles"
      :loading="loading"
      @change="handleTableChange"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useContentStore } from '@/stores/content'

const contentStore = useContentStore()
const articles = ref([])
const loading = ref(false)

const columns = [
  { title: '标题', dataIndex: 'title' },
  { title: '分类', dataIndex: 'category' },
  { title: '状态', dataIndex: 'status' },
  { title: '发布时间', dataIndex: 'publishedAt' },
  { title: '操作', dataIndex: 'actions' }
]

onMounted(async () => {
  loading.value = true
  articles.value = await contentStore.fetchArticles()
  loading.value = false
})

const handleCreate = () => {
  // 跳转到创建页面
}

const handleTableChange = (pagination: any) => {
  // 处理分页变化
}
</script>

调试技巧 ​

管理后台调试 ​

  1. Vue DevTools: 安装浏览器扩展
  2. Network: 查看 API 请求状态
  3. Console: 查看 SDK 日志输出

前台站点调试 ​

bash
# 开发模式
npm run dev:web

# SSR 调试
npm run dev:ssr

移动端调试 ​

bash
# H5 调试
npm run dev:h5

# 微信小程序调试
npm run dev:mp-weixin

测试 ​

单元测试 ​

bash
# 运行所有测试
npm run test

# 运行指定模块测试
npm run test -- packages/sdk

# 覆盖率报告
npm run test:coverage

E2E 测试 ​

bash
# 运行 E2E 测试
npm run test:e2e

# headed 模式
npm run test:e2e -- --headed

性能优化 ​

前端优化 ​

  1. SSR 渲染：前台站点使用服务端渲染，首屏秒开
  2. 图片懒加载：图片进入视口才加载
  3. 内容分页：列表页分页加载
  4. CDN 加速：静态资源 CDN 分发

服务端优化 ​

  1. 缓存策略：Redis 缓存热点数据
  2. 数据库优化：索引优化、查询优化
  3. 定时任务：异步处理耗时操作
  4. CDN 分发：媒体资源 CDN 加速

部署 ​

Docker 部署 ​

bash
# 构建镜像
docker build -t magicms:latest .

# 运行容器
docker run -d -p 8080:8080 magicms:latest

Kubernetes 部署 ​

bash
# 应用配置
kubectl apply -f k8s/

# 查看状态
kubectl get pods -n magicms

常见问题 ​

Q: SSR 渲染失败？ ​

A: 检查：

  1. Node.js 版本是否 >= 18
  2. 模板文件是否存在
  3. 数据接口是否正常

Q: AI 功能不可用？ ​

A: 检查：

  1. AI 引擎是否启用（VITE_AI_ENABLED=true）
  2. API Key 是否配置
  3. 大模型服务是否可达

Q: 多站点配置不生效？ ​

A: 检查：

  1. 站点域名是否正确配置
  2. Nginx 代理配置是否正确
  3. 站点状态是否启用

相关资源 ​