# iris-sfc 弃用通知

**日期**: 2026-05-16  
**状态**: ⚠️ 已弃用（Deprecated）  
**替代方案**: 使用 Vite 预编译 + iris-js 运行时

---

## 📢 弃用原因

iris-sfc 当前的实现存在以下根本性问题：

1. **不是真正的 Vue 编译器**
   - 只使用正则表达式提取和字符串替换
   - 无法生成正确的 Vue 3 render 函数
   - 不支持响应式、指令、组件等核心特性

2. **与运行时不兼容**
   - 生成的是 HTML 字符串而非 VNode 调用树
   - 无法与 iris 的 VTree 系统正确对接
   - 导致运行时错误：`TypeError: not a callable function`

3. **维护成本高**
   - 需要实现完整的 AST 解析、转换、代码生成
   - 与现有的 fervid、@vue/compiler-sfc 等成熟方案重复造轮子
   - 投入产出比低

---

## 🔄 替代方案

### 方案：预编译模式

**工作流**：

```bash
# 开发者使用 Vite 开发
cd examples/vue-demo
npm run dev  # Vite 热重载开发

# 构建产物供 iris 运行
npm run build  # 生成 dist/ 目录
```

**iris-cli 职责**：
- ❌ 不再负责编译 `.vue` 文件
- ✅ 只负责加载已编译的 JS 代码
- ✅ 执行渲染和事件处理

---

## 📅 迁移时间线

### Phase 1: 标记弃用（当前）

- [x] 添加弃用警告
- [x] 更新文档
- [ ] 创建迁移指南

### Phase 2: 功能冻结（1 周）

- [ ] 停止新增功能
- [ ] 只修复严重 bug
- [ ] 提供预编译示例

### Phase 3: 完全移除（2-4 周后）

- [ ] 从 iris-engine 移除依赖
- [ ] 从 workspace 移除 crate
- [ ] 清理相关代码

---

## 🛠️ 迁移指南

### 对于应用开发者

**之前**（运行时编译）：
```bash
iris-cli dev  # 直接运行 .vue 文件
```

**之后**（预编译）：
```bash
# 1. 使用 Vite 开发
npm run dev

# 2. 构建为 iris 可运行的格式
npm run build:iris

# 3. 运行
iris-cli dev --prebuilt dist/
```

### 对于库开发者

如果你的项目依赖 iris-sfc，建议：

1. **短期**：fork iris-sfc 并自行维护
2. **中期**：迁移到 fervid 或 @vue/compiler-sfc
3. **长期**：使用预编译模式

---

## 📊 影响评估

### 受影响的功能

| 功能 | 影响 | 替代方案 |
|------|------|---------|
| `.vue` 文件运行时编译 | ❌ 移除 | 使用 Vite 预编译 |
| HMR（热模块替换） | ⚠️ 降级 | Vite HMR |
| TypeScript 支持 | ✅ 保留 | Vite + swc |
| Scoped CSS | ✅ 保留 | Vite 插件 |
| 组件编译 | ❌ 移除 | Vite 预编译 |

### 不受影响的功能

- ✅ HTML 渲染
- ✅ GPU 渲染管线
- ✅ 布局计算（cssbox）
- ✅ 事件系统
- ✅ WebGPU 渲染

---

## ❓ FAQ

**Q: 为什么不在 iris-sfc 上集成 fervid？**

A: 集成 fervid 需要 2-3 周工作量，且需要深度适配 iris 的 VNode 系统。预编译模式可以立即解决问题，且与现有工具链（Vite）无缝集成。

**Q: 预编译模式会影响开发体验吗？**

A: 不会。Vite 提供优秀的 HMR 体验（<50ms），比运行时编译更快。开发者可以继续享受即时反馈。

**Q: 已有的 .vue 项目如何迁移？**

A: 只需添加 Vite 配置（已提供模板），然后使用 `npm run build:iris` 构建即可。

**Q: iris-sfc 会被完全删除吗？**

A: 是的，预计 2-4 周后从代码库中完全移除。如果需要，可以 fork 独立维护。

---

## 📞 联系方式

如有问题或建议，请：
- 提交 Issue: https://github.com/your-org/iris-webgpu/issues
- 参与讨论: https://github.com/your-org/iris-webgpu/discussions

---

**最后更新**: 2026-05-16
