快速开始

环境要求

• Node.js >= 18
• npm >= 9 或 pnpm >= 8
• Git

安装

克隆仓库

git clone https://github.com/gitcoffee-os/magicms.git
cd magicms

安装依赖

npm install
# 或
pnpm install

开发

启动开发服务器

npm run dev
# 或
pnpm dev

开发服务器启动后，访问 http://localhost:3000 即可预览。

构建生产版本

npm run build
# 或
pnpm build

构建产物将输出到 dist 目录。

项目结构

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

配置说明

基础配置

在项目根目录创建 .env 文件：

# 服务端地址
VITE_API_BASE_URL=http://localhost:8080

# 站点名称
VITE_APP_NAME=MagiCMS

# AI 引擎配置（可选）
VITE_AI_ENABLED=true
VITE_AI_MODEL=gpt-4

多站点配置

# 默认站点
VITE_SITE_ID=default

# 多站点模式
VITE_MULTI_SITE=true

AI 引擎配置（可选）

# AI 引擎开关
VITE_AI_ENABLED=true

# 大模型配置
VITE_AI_API_KEY=your_api_key
VITE_AI_MODEL=gpt-4
VITE_AI_BASE_URL=https://api.openai.com/v1

💡 AI 引擎为可插拔设计，不配置 AI 相关参数时，系统依然作为专业级 CMS 正常运行。

使用示例

创建内容模型

import { createModel } from '@magicms/sdk'

const articleModel = createModel({
  name: 'article',
  displayName: '文章',
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'content', type: 'richtext', required: true },
    { name: 'cover', type: 'image' },
    { name: 'category', type: 'relation', target: 'category' },
    { name: 'tags', type: 'relation', target: 'tag', multiple: true }
  ]
})

创建内容

import { MagiCMS } from '@magicms/sdk'

const cms = new MagiCMS({
  apiBaseUrl: 'http://localhost:8080',
  siteId: 'default'
})

// 创建文章
await cms.content.create('article', {
  title: 'Hello MagiCMS',
  content: '这是我的第一篇文章',
  category: 'tech',
  tags: ['cms', 'ai']
})

AI 辅助创作

// AI 生成文章大纲
const outline = await cms.ai.generateOutline({
  topic: 'AI 原生 CMS 的未来',
  style: 'professional'
})

// AI 智能翻译
const translated = await cms.ai.translate({
  contentId: 'article_123',
  targetLang: 'en'
})

// AI 生成封面图
const cover = await cms.ai.generateImage({
  prompt: '科技感 CMS 系统封面图',
  size: '1200x630'
})

常见问题

Q: 如何切换开发环境？

A: 使用 .env.development、.env.production 等文件来配置不同环境。

Q: 如何添加新的内容模型？

A: 在管理后台的「内容模型」页面中，点击「新建模型」，配置字段即可。

Q: 如何自定义主题？

A: 在 themes/ 目录下创建新主题，参考已有主题的结构进行开发。

Q: 如何启用/关闭 AI 引擎？

A: 在 .env 文件中设置 VITE_AI_ENABLED=true/false，或在管理后台的「系统设置」中切换。

下一步

• 开发指南 - 了解详细开发规范
• 功能特性 - 查看完整功能列表
• 贡献指南 - 参与项目贡献