@love-sqjm/magic 2026.4.15

package/doc/user-guide/index.md

@@ -0,0 +1,485 @@
+# Magic 使用指南
+
+## 目录
+
+1. [环境配置](#1-环境配置)
+2. [项目创建](#2-项目创建)
+3. [项目结构](#3-项目结构)
+4. [开发流程](#4-开发流程)
+5. [构建部署](#5-构建部署)
+6. [常见问题](#6-常见问题)
+
+---
+
+## 1. 环境配置
+
+### 1.1 系统要求
+
+| 要求 | 说明 |
+|------|------|
+| 操作系统 | Windows |
+| 运行时 | Bun.js |
+| Node.js | 可选（仅用于辅助工具） |
+
+### 1.2 安装 Bun.js
+
+Magic 基于 Bun.js 运行，必须先安装 Bun。
+
+**方法一：使用 PowerShell（推荐）**
+
+```powershell
+powershell -ExecutionPolicy Bypass -Command "irm bun.sh/install.ps1 | iex"
+```
+
+**方法二：使用 npm**
+
+```bash
+npm install -g bun
+```
+
+**验证安装**
+
+```bash
+bun --version
+```
+
+### 1.3 安装 Magic CLI
+
+```bash
+bun install -g magic-bun
+```
+
+**验证安装**
+
+```bash
+magic --version
+```
+
+### 1.4 开发工具推荐
+
+| 工具 | 说明 |
+|------|------|
+| VS Code | 代码编辑器 |
+| Thunder Client | API 测试（可选） |
+| Chrome DevTools | 浏览器调试 |
+
+---
+
+## 2. 项目创建
+
+### 2.1 创建 Web 项目
+
+```bash
+magic init my-web-app --web
+```
+
+### 2.2 创建 Node-Webkit 桌面项目
+
+```bash
+magic init my-desktop-app --node-webkit
+```
+
+### 2.3 创建模块项目
+
+```bash
+magic init my-module --module
+```
+
+### 2.4 项目初始化输出
+
+```
+my-web-app/
+├── app/
+│   ├── app.xml          # 应用配置
+│   └── index.m          # 入口模块 (自动创建)
+├── build.toml           # 构建配置
+└── package.json
+```
+
+### 2.5 创建组件文件
+
+使用 `create-m` 命令创建新的 `.m` 组件文件：
+
+```bash
+magic create-m button    # 创建 button.m
+magic create-m mycomponent
+```
+
+文件会创建在当前项目目录下（与 `build.toml` 同级）。
+
+---
+
+## 3. 项目结构
+
+### 3.1 目录说明
+
+```
+project/
+├── app/                 # 源码目录
+│   ├── app.xml         # 应用配置
+│   ├── index.m         # 入口模块
+│   ├── components/     # 组件目录
+│   │   ├── header.m
+│   │   └── footer.m
+│   ├── pages/          # 页面目录
+│   │   ├── home.m
+│   │   └── about.m
+│   └── assets/         # 资源目录
+│       ├── images/
+│       └── styles/
+├── build/              # 构建输出目录（自动生成）
+│   ├── index.html
+│   ├── magic/
+│   └── ...
+└── build.toml          # 构建配置
+```
+
+### 3.2 入口文件
+
+`app/index.m` 是应用入口模块（初始化时自动创建）：
+
+```xml
+<import
+	root=""
+>
+</import>
+
+<template>
+    <h1 #id="h1">hello magic!</h1>
+</template>
+
+<script code="global">
+	 const {
+    } = $id();
+</script>
+
+<script code="listen">
+</script>
+
+<script>
+</script>
+
+<script code="interface">
+</script>
+
+<css scope="" default-theme>
+</css>
+
+<css scope="#id:h1">
+    & {
+        font-size: 32px;
+    }
+</css>
+```
+
+---
+
+## 4. 开发流程
+
+### 4.1 启动开发服务器
+
+```bash
+cd my-web-app
+magic run
+```
+
+这将：
+1. 启动 HTTP 服务器（默认 `http://localhost:8088`）
+2. 自动打开浏览器
+3. 开启热更新监听
+
+### 4.2 编辑代码
+
+**创建新组件**
+
+可以使用 `create-m` 命令快速创建组件模板：
+
+```bash
+magic create-m greeting    # 创建 greeting.m
+```
+
+然后编辑生成的文件：
+
+```xml
+<!-- app/components/greeting.m -->
+<template>
+    <div #id="greeting">
+        <h1 #id="message">Hello!</h1>
+        <button #id="btn" @click="sayHello">点击</button>
+    </div>
+</template>
+
+<script code="global">
+const { $message, $btn } = $id();
+</script>
+
+<script code="event">
+sayHello = () => {
+    $message.textContent = "Hello, Magic!";
+}
+</script>
+
+<css scope="#id:greeting">
+& {
+    text-align: center;
+    padding: 20px;
+}
+</css>
+```
+
+**在页面中使用组件**
+
+```xml
+<!-- app/pages/home.m -->
+<import root="../components">
+    <greeting/>
+</import>
+
+<template>
+    <div #id="home-page">
+        <greeting/>
+    </div>
+</template>
+```
+
+### 4.3 热更新
+
+修改 `.m` 文件后，浏览器会自动刷新页面。
+
+**手动刷新**
+
+如果热更新未生效，可以手动刷新浏览器或重启服务器。
+
+---
+
+## 5. 构建部署
+
+### 5.1 开发模式构建
+
+```bash
+magic build
+```
+
+输出结构：
+
+```
+build/
+├── index.html
+├── magic/
+│   ├── runtime.js
+│   ├── runtime.css
+│   ├── index.js
+│   └── index.css
+└── ...（其他资源）
+```
+
+### 5.2 生产模式构建
+
+修改 `build.toml`:
+
+```toml
+[build]
+model = "release"
+
+[build.optimize.min-code]
+js = true
+css = true
+html = true
+```
+
+然后执行：
+
+```bash
+magic build
+```
+
+### 5.3 部署 Web 应用
+
+**静态托管**
+
+将 `build/` 目录部署到任何静态托管服务：
+
+- Nginx
+- Apache
+- Vercel
+- Netlify
+- GitHub Pages
+
+**Nginx 配置示例**
+
+```nginx
+server {
+    listen 80;
+    server_name example.com;
+    root /path/to/project/build;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}
+```
+
+**Node.js 服务**
+
+可以配置为 SPA 模式：
+
+```javascript
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+const server = http.createServer((req, res) => {
+    let filePath = path.join(__dirname, 'build', req.url === '/' ? 'index.html' : req.url);
+    
+    // SPA fallback
+    if (!fs.existsSync(filePath)) {
+        filePath = path.join(__dirname, 'build', 'index.html');
+    }
+    
+    const ext = path.extname(filePath);
+    const contentTypes = {
+        '.html': 'text/html',
+        '.js': 'application/javascript',
+        '.css': 'text/css',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg'
+    };
+    
+    res.setHeader('Content-Type', contentTypes[ext] || 'text/plain');
+    fs.createReadStream(filePath).pipe(res);
+});
+
+server.listen(3000);
+```
+
+---
+
+## 6. 常见问题
+
+### Q1: 报错 "不是 Bun 环境，无法使用！"
+
+**原因:** 未安装 Bun 或不在 Bun 环境中运行。
+
+**解决:**
+```bash
+# 确认 Bun 已安装
+bun --version
+
+# 确认使用 bun 运行
+bun magic build
+```
+
+### Q2: 报错 "缺少入口文件"
+
+**原因:** `build.toml` 中指定的入口文件不存在。
+
+**解决:** 确保 `app/index.m` 文件存在：
+
+```toml
+[config]
+main = "index"
+```
+
+### Q3: 热更新不生效
+
+**原因:** WebSocket 连接问题或文件监听失败。
+
+**解决:**
+1. 检查浏览器控制台是否有 WebSocket 连接错误
+2. 重启开发服务器
+3. 手动刷新浏览器
+
+### Q4: 样式不生效
+
+**原因:** CSS 作用域选择器使用错误。
+
+**解决:** 使用正确的 `#id:xx` 语法：
+
+```xml
+<!-- 正确 -->
+<css scope="#id:myComponent">
+
+<!-- 错误 -->
+<css scope=".myComponent">
+```
+
+### Q5: 模块导入失败
+
+**原因:** 模块路径配置错误。
+
+**解决:**
+1. 检查 `import` 标签的 `root` 属性
+2. 确认目标 `.m` 文件存在
+3. 检查模块名称拼写
+
+### Q6: 如何调试？
+
+**方法一：浏览器控制台**
+
+```javascript
+console.log("Debug info:", someValue);
+```
+
+**方法二：查看构建日志**
+
+构建日志位于项目根目录的 `Magic.log`。
+
+**方法三：debug 模式构建**
+
+```toml
+[build]
+model = "debug"
+```
+
+生成未压缩的代码便于调试。
+
+### Q7: 如何处理第三方库？
+
+**引入 JavaScript 库**
+
+在 `app.xml` 中引入：
+
+```xml
+<app lang="zh">
+    <import dir=".">
+        <js src="lib/jquery.min.js"/>
+    </import>
+</app>
+```
+
+**引入 CSS 库**
+
+```xml
+<app lang="zh">
+    <import dir=".">
+        <css src="lib/bootstrap.min.css"/>
+    </import>
+</app>
+```
+
+### Q8: 如何处理图片等静态资源？
+
+将资源放在 `app/` 目录，构建时会自动复制到 `build/` 目录：
+
+```
+app/
+├── images/
+│   └── logo.png
+└── index.m
+```
+
+在代码中引用：
+
+```xml
+<img src="./images/logo.png"/>
+```
+
+---
+
+## 下一步
+
+- 查看 [架构文档](./architecture.md) 深入了解系统设计
+- 查看 [.m 文件规范](./magic-file/index.md) 学习组件开发
+- 查看 [API 参考](./api/index.md) 了解 Runtime API
+- 查看 [配置手册](./config-reference.md) 掌握配置选项