Velxio的.vlx项目文件详解：如何免服务器保存、分享并版本兼容你的电路设计
【免费下载链接】velxioEmulate Arduino, ESP32 & Raspberry Pi. in your browser. Write code, compile, and run on 19 real boards — Arduino Uno, ESP32, ESP32-C3, Raspberry Pi Pico, Raspberry Pi 3, and more. No hardware, no cloud, no limits.. Discord: https://discord.gg/3mARjJrh4E项目地址: https://gitcode.com/gh_mirrors/ve/velxio
Velxio 是一款在浏览器中直接编写、编译并运行 Arduino、ESP32、树莓派等 19 块真实开发板的在线电路设计仿真器，无需硬件、无需云端。而.vlx 项目文件就是它在"零服务器"模式下保存电路设计的核心机制：一个单文件 JSON 快照，把你的画布、代码和连线完整打包，随下随走、随发随开。
为什么 Velxio 需要 .vlx 文件？
开源版（OSS）Velxio 的架构是无服务器状态（Stateless Backend）：没有数据库、没有账号体系、没有任何服务端项目持久化。你在编辑器里搭的电路刷新页面就会消失。
为了让自托管用户也能拥有可靠的项目保存能力，Velxio 把"保存"做成了一个浏览器直接下载的文件——.vlx：
- 点Save= 下载当前工作区的
.vlx快照 - 点Open= 从
.vlx文件恢复整个工程 - 工程存在哪儿，你的项目就在哪儿（网盘、Git 仓库、U 盘都行）
这一设计的说明可见 docs/ARCHITECTURE.md 的 "Persistence" 章节。
.vlx 项目文件里到底装了什么？
.vlx本质是一个格式为velxio-project、带版本号的 JSON 对象。一次导出的完整内容如下：
| 字段 | 说明 |
|---|---|
format/version | 格式标识（velxio-project）与格式版本号 |
exportedAt | 导出的 ISO 时间戳 |
name | 项目名称（可选，用于生成文件名） |
boards | 所有开发板：类型、位置、语言模式、波特率、内置 SD 卡文件、库清单（libraries） |
fileGroups | 每块板 / 每个自定义芯片的全部源码文件 |
folderGroups | 空文件夹结构（旧版本文件可无此字段） |
components | 所有元件：类型、位置、属性、旋转 |
wires | 所有连线：端点、颜色、信号类型 |
activeBoardId | 当前激活的板 |
这个快照是无损的：连自定义芯片（custom chip）的自带程序组（group-chip-<id>）、板卡内置 SD 槽上传的文件、声明的编译库清单都会原样随工程走。实现代码位于 frontend/src/utils/vlxFile.ts，其中buildVlxPayload()负责打包、parseVlxFile()负责读取校验。
三步导出 .vlx：最快保存方法
- 在编辑器菜单File → Save project（开源版按钮行为是"下载 .vlx"，Pro 版则打开"保存到账号"弹窗）；
- 浏览器保存对话框中选择位置，文件名由项目名自动清洗生成（只保留字母、数字、
-_.，超长截断，自动补.vlx后缀）； - 下次打开时File → Open .vlx，拖拽或选择文件即可完整还原电路设计。
保存按钮的注册逻辑在 frontend/src/lib/proSaveAction.ts：开源版默认行为就是触发triggerDownloadVlx()下载快照，Pro 版则通过 overlay 替换为账号保存。
桌面应用（Tauri）进一步免去了浏览器下载弹窗，可直接从文件系统打开.vlx，详见 docs/desktop-app.md。
如何免服务器分享电路设计给别人？
开源版的分享方式简单粗暴又可靠：把.vlx文件发出去就是分享。
- 通过聊天工具、邮件、网盘或直接提交到代码仓库，对方在 Velxio 里点 Open 即可完整复现你的电路设计；
- 由于
.vlx的字段结构与 Pro 服务端/api/projects/的保存报文刻意保持一致，Pro 用户可以从 Pro 导出、导入开源版（反之亦然），双方互认工程内容； - 导入时 Velxio 会先切断当前项目身份再写入状态（见 vlxFile.ts 中
importVlxFile()的clearCurrentProject()调用），避免新内容误覆盖你已保存的旧工程。
版本兼容：.vlx 如何保证未来还能打开？
.vlx采用显式版本号 + 防御式校验双保险：
| 场景 | 行为 |
|---|---|
文件version高于当前 Velxio 支持的最高版本 | 明确报错："此文件使用 v2 格式，请升级 Velxio"，不会加载半截数据 |
新版可选字段（如folderGroups、libraries、sdFiles）在旧文件中缺失 | 正常加载，优雅降级 |
| 手动编辑过或字段错乱 | validatePayload()逐项校验并给出人类可读的错误原因，坏字段（如folderGroups）会静默丢弃而非崩溃 |
也就是说：旧文件永远能在新版打开，新文件会明确提示升级，这正是"版本兼容"承诺的由来。
关键源码与文档路径
- 核心格式定义与读写：frontend/src/utils/vlxFile.ts
- 保存按钮行为分发：frontend/src/lib/proSaveAction.ts
- 登录往返草稿（复用同一
.vlx序列化存入 sessionStorage）：frontend/src/utils/workspaceDraft.ts - 架构说明：docs/ARCHITECTURE.md
- 路线图中的
.vlx规划：docs/roadmap.md - 导入导出回归测试：frontend/src/tests/vlx-export-command.test.ts
常见疑问速答
Q：.vlx 文件能用文本编辑器打开吗？可以，它就是格式化 JSON（JSON.stringify(payload, null, 2)），可以手动改名、改属性，再拖回 Velxio 加载。
Q：.vlx 和 wokwi.json 有什么区别？.vlx覆盖范围更广：多块开发板、多文件代码组、自定义芯片程序、内置 SD 文件、库声明都在一个文件里往返，而不是只描述一块板。
Q：刷新页面会丢工作吗？匿名工作区刷新即失；但登录往返的短暂导航场景，Velxio 会用同一份.vlx序列化把草稿暂存到 sessionStorage 自动恢复。养成"常按 Save"的习惯，工程永远在你自己的文件里。
💡 小结：
.vlx= 电路设计 + 全部源码 + 板卡配置的单文件无损快照。保存是下载、分享是发文件、兼容靠版本号——全程无需任何服务器。
【免费下载链接】velxioEmulate Arduino, ESP32 & Raspberry Pi. in your browser. Write code, compile, and run on 19 real boards — Arduino Uno, ESP32, ESP32-C3, Raspberry Pi Pico, Raspberry Pi 3, and more. No hardware, no cloud, no limits.. Discord: https://discord.gg/3mARjJrh4E项目地址: https://gitcode.com/gh_mirrors/ve/velxio
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
