简介这是一套基于Luckysheet的在线协作Excel表格工具面向需要快速搭建轻量级表格协同环境的团队或个人免去数据库配置直接调用Excel文件即可运行并内置60秒自动保存机制解压后执行RUNme.bat即可启动服务。资源共2000个文件主体为1887个Python脚本承担服务启动、表格解析与协作逻辑另有46个C源码与30个头文件用于底层编译扩展少量txt/md/xml文件提供说明与配置整体压缩包约55.97MB。目前已有620人学习下载。使用者可直接部署在局域网内支持多人同时编辑同一份Excel表格无需额外安装数据库或复杂环境适合中小型团队的项目进度管理、数据收集与日常报表协作。项目结构清晰启动脚本与自动保存机制一并打包既可作为Luckysheet前端与Python后端结合的实战范例也便于参考其文件直读、定时存档等设计思路进行二次开发。 部门领导丢给我一个算不上复杂的任务给十来个人弄一个能同时编辑的共享表格要求只有两条——别申请数据库别搞复杂部署最好把文件发过去就能用。我在网上翻了半天最后选了 luckysheet 这个开源在线表格组件做出了一个真正免数据库的在线 EXCEL 协作工具解压项目包双击 RUNme.bat浏览器打开就能看到一份和 Excel 几乎长得一样的表格它可以直接读取本地 .xlsx 文件所有修改 60 秒自动保存回文件全程不需要安装数据库也不需要启动重型中间件。这套方案我自己用了大半年中间踩了不少坑也优化了好几轮。今天把整个项目的设计思路、核心代码和避坑经验完整写出来。如果你属于下面这几类人这篇应该能直接帮你省掉几天的折腾时间要给团队快速搭一个内网协作表格、手头有现成 Excel 文件想直接在线编辑、没条件用数据库、想搞清楚 luckysheet 这类组件和后端到底怎么衔接。1. 为什么把在线表格做成了不带数据库的样子1.1 传统在线协作表格的复杂度都在哪一提到在线协作 Excel很多人的第一反应是前端表格 WebSocket 协同 后端服务 数据库存单元格。这套组合本身没错像我们熟知的很多商业表格产品就是这么做的但问题是它太重了。为了一个十来个人用的内部工具你要维护用户表、权限表、单元格数据表、操作日志表还要处理多人同时改同一个单元格的冲突合并光想想就头疼。我一开始也顺着这个思路想过后端用 Node.js 或者 Java数据落到 MySQL前端用 luckysheet 连接。可真动手后我发现这个需求只有我一个半吊子后端数据库还得跟运维申请审批流程都要走一星期。于是我问了自己一个关键问题我到底需不需要数据库答案是不需要。原因很朴素。这个场景下真正的需求是把一份 Excel 文件放到网页上让大家编辑编辑结果不能丢而不是做一个多租户的 SaaS 表格系统。那我完全可以绕开数据库直接把 .xlsx 文件当成存储介质——读取时把文件解析进编辑器保存时把编辑器里的数据整体写回文件。这就是标题里说的免数据库直接调用 EXCEL 文件。1.2 文件即存储适合什么场景这套思路听起来省事但它不是银弹先把自己的使用场景说清楚你才能判断要不要照搬。适合的场景有几个共同点首先是人数少同时在线编辑的人不超过二三十个这决定了大家不会在一个密集时间窗口里疯狂写入其次是内网或者小范围使用网络条件可控不需要跨地域协作然后是数据量不大表格行数在几万行以内单文件几十 MB 封顶。这种需求在传统企业、学校实验室、项目组内部特别常见大家并不是要一个数据库系统只是想把原来传来传去的 Excel 收敛到同一个网页上。不适合的场景也很明显如果你要支持上百人同时编辑或者对审计日志、细粒度权限有硬性要求或者表格里每天要写入几十万行数据那不要用这个方案。文件即存储的本质是用最终覆盖代替事务合并并发一高就会出覆盖问题后面我会专门讲怎么尽量回避。2. 整体结构与核心依赖一条链路串起来2.1 前端luckysheet 负责编辑体验luckysheet 是国产开源的一款类 Excel 在线表格组件官方文档说它支持多种格式、公式、图表、数据透视等功能实际用下来日常的编辑、合并单元格、样式、公式、条件格式这些都没问题界面和交互逻辑跟 Excel 非常接近用户不需要重新学习。我选它而不是其他表格库核心就三点第一是社区版免费MIT 协议二次开发没有授权顾虑第二是 API 足够简单官方封装了创建实例、获取全部 Sheet 数据的方法前后端衔接成本低第三是部署零负担它就是一堆静态文件只需要一个静态服务器把它跑起来不需要单独安装任何运行时框架。前端只需要引几个 JS/CSS 文件然后调用luckysheet.create()就能把一个空表格渲染出来这对接下来的项目结构很友好。2.2 后端Node.js SheetJS 负责读写文件后端我选了 Node.js 加 Express配合 SheetJS 社区版库npm 包名是xlsx来做 Excel 文件的解析和生成。选 Node 的原因很简单跟前端同一门语言处理 JSON 天然顺畅而且手头这台 Windows 机器本身就有了 Node 环境RUNme 脚本可以直接调用。SheetJS 是读写字幕 xlsx 文件的事实标准库它能解析 Excel 文件里的工作表、行列单元格、合并区域也能把二维数组转换成工作表再写回 xlsx。这里有一个很重要的点SheetJS 社区版不支持样式解析也就是单元格的字体、颜色、背景色这些信息读写之后会丢。所以我在设计的时候就明确告诉使用者这个工具承担的是内容协作职责不是像素级复刻原文件职责。如果原始 Excel 里有大量复杂样式打开后肯定会变样这一点必须提前跟业务方对齐否则会被当成 Bug 投诉。2.3 数据流的三种状态整个系统里数据有三种形态理清这三种形态后面的代码就顺了。第一种是磁盘上的 .xlsx 物理文件它是一切数据的源头第二种是 luckysheet 编辑器内部的 JSON 数据结构它描述了一个工作簿里有哪些 Sheet、每个 Sheet 的行列、单元格值、合并信息第三种是后端做转换时的二维数组中间态SheetJS 读写 Excel 时最常接受这种格式。用户打开页面时后端把 .xlsx 读出来转成第二种 JSON 结构交给 luckysheet 渲染。用户在网页上编辑时数据只存在于前端内存里不会立刻写文件。每隔 60 秒前端把当前的第二种 JSON 数据 POST 到后端后端把它转回第一种 .xlsx 文件覆盖保存。整个链路里没有任何数据库数据只在一个方向流转文件 → 编辑器 → 文件。3. 核心实现Excel 加载、回写与60秒自动保存3.1 项目骨架与依赖安装先看目录结构和依赖这个项目精简到只有三个核心文件excel-collab/ ├── public/ │ └── index.html # luckysheet 前端页面 ├── data/ │ └── 团队协作表.xlsx # 要读取和写入的 Excel 文件 ├── server.js # Express 后端提供页面和保存接口 ├── RUNme.bat # Windows 一键启动 └── RUNme.sh # macOS/Linux 一键启动后端只需要两个依赖express和xlsxpackage.json写清楚版本就行。安装时用国内镜像会快很多npm install express xlsx --registryhttps://registry.npmmirror.com启动时机是先在data/下放一个.xlsx文件名字可以自己定然后把主文件路径写进server.js顶部的常量配置里。服务跑起来后后端会先把文件里所有 Sheet 解析成 luckysheet 能识别的结构再通过页面接口吐给前端前端拿到后调用luckysheet.create()渲染。整个流程非常短适合不懂前端的读者往下跟。3.2 Excel 怎么加载进编辑器这是整个项目里最容易写错的地方因为我最初想当然地以为把 xlsx 数据原样塞给 luckysheet 就行结果页面白屏。后来看文档才发现两者数据结构不一样必须做一层转换。SheetJS 读文件后拿到的是Workbook对象我重点用两个东西wb.SheetNames拿工作表名字列表wb.Sheets[sheetName]拿具体工作表。要把一个工作表转成 luckysheet 的data二维数组我写了一个转换函数const XLSX require(xlsx); function sheetToLuckysheetData(ws) { // header: 1 表示把工作表转成二维数组不把第一行当表头 const rows XLSX.utils.sheet_to_json(ws, { header: 1 }); const data []; for (let r 0; r rows.length; r) { if (!data[r]) data[r] []; for (let c 0; c rows[r].length; c) { data[r][c] { v: rows[r][c] }; } } return data; }这里有几个很实用的细节。rows[r][c]原始值可能是字符串、数字、日期、公式等luckysheet 的统一格式是{ v: 值 }所以要把每个格子包一层。空行和空列不需要补到满二维数组是稀疏的也没关系因为 renderer 会自己处理。公式值直接放进v就行luckysheet 看到v字段以等号开头会把它当成公式重新计算。但真正让我抓狂的是合并单元格。Excel 里的合并区域存在工作表的!merges属性里luckysheet 却不认识这个属性它有自己的合并配置长这样config { merge: { // key 是 起始行_起始列 0_0: { r: 0, c: 0, rs: 2, cs: 3 } } }意思是第 0 行第 0 列开始向下合并 2 行、向右合并 3 列。所以读文件时要把!merges循环一遍转换 key 的格式function parseMerges(ws) { const merge {}; if (ws[!merges]) { ws[!merges].forEach((m) { const key ${m.s.r}_${m.s.c}; merge[key] { r: m.s.r, c: m.s.c, rs: m.e.r - m.s.r 1, cs: m.e.c - m.s.c 1 }; }); } return merge; }最后组装成 luckysheet 能识别的 sheet 对象const sheets wb.SheetNames.map((name, idx) ({ name, index: idx, data: [sheetToLuckysheetData(wb.Sheets[name])], config: { merge: parseMerges(wb.Sheets[name]) } }));这里data注意要包一层数组表示这是整个 sheet 的数据集。这个结构我调了两版才跑通经验就是多看官方的接口说明别凭感觉猜格式。3.3 60 秒自动保存定时器、脏标记、保存锁前端拿到 sheets 数据后初始化编辑器luckysheet.create({ container: luckysheet, title: 团队协作表, data: sheets, // 后端转换好的结构 column: 26, row: 200 });自动保存逻辑的关键不是每 60 秒无脑保存一次而是讲究策略地保存否则会觉得卡顿。我用了一个脏标记 定时器 保存锁的组合。首先定义一个dirty标志luckysheet 的updated事件会在内容真实变化时触发我把dirty置为true。然后开一个 60 秒的定时器每次触发时检查dirty如果是true才发保存请求发完立即把dirty重置为false。这样没有修改的时候文件不会被反复无意义地覆盖。保存锁是为了防止上一次保存还没完成下一次定时器又触发了。我用一个布尔变量isSaving请求开始置true返回或报错后置falsesetInterval(() { if (!dirty || isSaving) return; const allSheets luckysheet.getAllSheets(); fetch(/api/save, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ sheets: allSheets }) }).then(() { dirty false; isSaving false; }) .catch(() { isSaving false; }); isSaving true; }, 60 * 1000);后端/api/save接口把sheets数组转回 xlsx 文件。这个转换是前面过程的逆操作每个 sheet 的data[0]是二维数组先把每个格子的v字段提取出来得到二维数组再用XLSX.utils.aoa_to_sheet()转回工作表。合并配置也别忘了还原app.post(/api/save, (req, res) { const sheets req.body.sheets; const wb XLSX.utils.book_new(); sheets.forEach((sheet) { const rows sheet.data[0].map(row row.map(cell cell ? cell.v : null)); const ws XLSX.utils.aoa_to_sheet(rows); // 合并信息还原成 !merges if (sheet.config sheet.config.merge) { ws[!merges] Object.values(sheet.config.merge).map(m ({ s: { r: m.r, c: m.c }, e: { r: m.r m.rs - 1, c: m.c m.cs - 1 } })); } XLSX.utils.book_append_sheet(wb, ws, sheet.name); }); XLSX.writeFile(wb, XLSX_FILE); res.json({ ok: true }); });这里再提醒一句保存一定要先写临时文件再替换目标文件。我最初直接writeFile覆盖目标路径结果有一次保存过程中机器断电原文件直接坏了。后来改成writeFile到同一个目录下的临时文件再用fs.renameSync原子替换再也没坏过文件。临时目录遗留文件定期清理即可。4. RUNme 一键启动是怎么设计的4.1 一键启动脚本要解决的问题标题里写了解压直接运行 RUNme这是整个项目体验的关键。设计这个脚本的时候我给自己定了个目标让一个完全不懂命令行的同事也能启动服务。这意味着脚本要自动做完三件事第一检查电脑上有没有 Node.js 环境第二首次运行自动安装依赖第三准备好数据目录并启动服务。如果这三件事都让使用者手动做那这套免数据库方案的价值就少了一大半。手动装依赖、敲命令这些步骤对程序员是家常便饭但对大多数人就是门槛。所以我把所有能自动化的步骤全都塞进了脚本里用户唯一要做的就是双击。4.2 Windows 与 macOS/Linux 两版脚本Windows 环境我用批处理脚本这是最老土也最通用的方式任何 Windows 机器都能直接双击运行echo off chcp 65001 nul cd /d %~dp0 where node nul 2nul if %errorlevel% neq 0 ( echo [RUNme] 未检测到 Node.js请先安装 Node.js 16 或更高版本 pause exit /b 1 ) if not exist node_modules ( echo [RUNme] 首次运行正在安装依赖... npm install --registryhttps://registry.npmmirror.com ) if not exist data mkdir data echo [RUNme] 启动中浏览器将自动打开 http://localhost:3000 start http://localhost:3000 node server.jsmacOS/Linux 用户会用到 shell 脚本逻辑完全一致只有自动打开浏览器的命令不同#!/bin/bash cd $(dirname $0) if ! command -v node /dev/null; then echo [RUNme] 未检测到 Node.js请先安装 Node.js 16 exit 1 fi [ -d node_modules ] || npm install --registryhttps://registry.npmmirror.com [ -d data ] || mkdir data open http://localhost:3000 2/dev/null || xdg-open http://localhost:3000 2/dev/null || true node server.js有一点我第一版做漏了server.js里如果用相对路径读文件脚本必须在项目根目录执行才行否则会报文件不存在。所以脚本开头第一行用法必须写cd /d %~dp0或cd $(dirname $0)强制把当前目录切到脚本所在目录。这个一行代码解决的问题当时让我排查了整整二十分钟运行路径问题在 Node 项目里太常见了。4.3 首次运行会碰到的环境和端口问题实际给同事部署时我碰到过三类环境相关的问题。第一类是电脑上根本没有 Node.js双击后会黑屏闪退没有任何提示。所以脚本里where node探活那一段一定要保留并且用pause让窗口停留否则报错信息一闪而过使用者只会觉得双击没反应。后来我在少数几台机器上还遇到过 Node 版本太老的情况luckysheet 本身对版本要求不高但 Express 新版依赖 Node 16脚本里加一个版本提示更稳妥。第二类是端口占用。如果 3000 端口已经被别的程序占用Node 启动会报EADDRINUSE。我在server.js里加了一个自动换端口的逻辑监听失败就尝试 3001、3002直到成功然后控制台打印出实际地址。这个改动表面上不起眼实际用起来明显提升了大伙儿的信心。第三类是杀毒软件误报。Windows 系统有时候会把不认识的新脚本和临时文件判断为风险行为导致写入 data 目录失败。解决办法是让使用者把项目目录加入信任区或者把节点进程加白名单一般内网办公电脑安全软件都能设置。这个问题不是代码能完全解决的但提前在文档里写清楚能少接很多求助电话。5. 用了一段时间后我踩过的坑和优化建议5.1 文件覆盖写坏的教训以及接下来的备份策略文件覆盖写坏这个问题前面提过一嘴但我想再单独拿出来说因为它是整个项目里最严重的一次故障。有一天同事跟我反馈说表格打开是空的我上服务器一看data 目录下那个 xlsx 文件大小变成了 0 字节。排查半天发现是保存过程中机器突然重启文件写到一半没写完原文件被截断。从那以后我把保存逻辑改成了临时文件 原子替换并且加了一个自动备份机制每次保存前先把当前文件复制一份到data/backup/目录按时间戳命名只保留最近 10 份。这样即使新的保存把文件写坏了也能从备份里找回几分钟前的版本。这个备份策略成本极低但给这个免数据库方案补上了最后一块安全短板。5.2 多人同时编辑的覆盖风险怎么尽量回避文件即存储方案最大的天然缺陷就是多人同时编辑时会出现后写覆盖先写。两个人同时打开同一份表格A 改了第一行B 改了第二行A 先保存B 后保存B 把整个文件覆盖掉A 的修改就丢了。这个问题在早期使用中是真实发生过的。我的应对策略分两层。第一层是使用习惯层面我在前端页面上加了一个横幅提示显示当前在线人数并提醒多人同时编辑时请避免同时改同一区域。第二层是技术层面在 luckysheet 里禁用了单元格锁定之外的一些并发敏感操作把allowUpdate选项关掉不让前端自动做基于数据的实时协同。如果你真的需要多人实时协同要做冲突合并那必须上类似操作日志、协同算法这类东西那就超出这个免数据库方案的范畴了需要换架构。5.3 那些打开后变样的 Excel 特性需要提前说清楚使用中最容易引发不满的其实是格式兼容问题。有同事拿了一个特别复杂的 Excel 进来里面有数据透视表、图表、条件格式、冻结窗格、批注打开后发现透视表和图表不显示批注也不见了各种色块也没了。这种变样不是 luckysheet 的问题而是 SheetJS 社区版能力边界决定的——它主要解析值和结构复杂对象和样式一概不支持。我的建议是上线前做一次格式摸底把团队里常用的 Excel 文件类型列出来逐一测试转换效果。如果你的使用场景是数据录入和基础表格协作完全没有问题如果重度依赖图表和数据透视表这个方案就满足不了需要评估 luckysheet 官方也有的一些进阶方案或者直接考虑商业表格产品。还有一个容易被忽略的点是保存回 .xlsx 后你再用桌面版 Excel 打开有些在网页里看起来正常的单元格到 Excel 里可能会显示成科学计数法比如长数字、身份证号。我在转换函数里对纯数字做了判断超过 11 位的数字强制转成字符串再写入这个细节虽然小但直接决定了导出的文件能不能被别人正常使用。最后分享一个我个人的习惯不管自动保存做得多稳每周五下午我都会手动备份一次 data 整个目录打包放到另一个磁盘。这不是不信任代码而是这类文件即存储的项目整个系统的命脉就在这个文件夹里核心资产怎么强调备份都不过分。本文还有配套的精品资源点击获取
免数据库搭建在线Excel协作工具：Luckysheet+Node.js文件存储实战
简介这是一套基于Luckysheet的在线协作Excel表格工具面向需要快速搭建轻量级表格协同环境的团队或个人免去数据库配置直接调用Excel文件即可运行并内置60秒自动保存机制解压后执行RUNme.bat即可启动服务。资源共2000个文件主体为1887个Python脚本承担服务启动、表格解析与协作逻辑另有46个C源码与30个头文件用于底层编译扩展少量txt/md/xml文件提供说明与配置整体压缩包约55.97MB。目前已有620人学习下载。使用者可直接部署在局域网内支持多人同时编辑同一份Excel表格无需额外安装数据库或复杂环境适合中小型团队的项目进度管理、数据收集与日常报表协作。项目结构清晰启动脚本与自动保存机制一并打包既可作为Luckysheet前端与Python后端结合的实战范例也便于参考其文件直读、定时存档等设计思路进行二次开发。 部门领导丢给我一个算不上复杂的任务给十来个人弄一个能同时编辑的共享表格要求只有两条——别申请数据库别搞复杂部署最好把文件发过去就能用。我在网上翻了半天最后选了 luckysheet 这个开源在线表格组件做出了一个真正免数据库的在线 EXCEL 协作工具解压项目包双击 RUNme.bat浏览器打开就能看到一份和 Excel 几乎长得一样的表格它可以直接读取本地 .xlsx 文件所有修改 60 秒自动保存回文件全程不需要安装数据库也不需要启动重型中间件。这套方案我自己用了大半年中间踩了不少坑也优化了好几轮。今天把整个项目的设计思路、核心代码和避坑经验完整写出来。如果你属于下面这几类人这篇应该能直接帮你省掉几天的折腾时间要给团队快速搭一个内网协作表格、手头有现成 Excel 文件想直接在线编辑、没条件用数据库、想搞清楚 luckysheet 这类组件和后端到底怎么衔接。1. 为什么把在线表格做成了不带数据库的样子1.1 传统在线协作表格的复杂度都在哪一提到在线协作 Excel很多人的第一反应是前端表格 WebSocket 协同 后端服务 数据库存单元格。这套组合本身没错像我们熟知的很多商业表格产品就是这么做的但问题是它太重了。为了一个十来个人用的内部工具你要维护用户表、权限表、单元格数据表、操作日志表还要处理多人同时改同一个单元格的冲突合并光想想就头疼。我一开始也顺着这个思路想过后端用 Node.js 或者 Java数据落到 MySQL前端用 luckysheet 连接。可真动手后我发现这个需求只有我一个半吊子后端数据库还得跟运维申请审批流程都要走一星期。于是我问了自己一个关键问题我到底需不需要数据库答案是不需要。原因很朴素。这个场景下真正的需求是把一份 Excel 文件放到网页上让大家编辑编辑结果不能丢而不是做一个多租户的 SaaS 表格系统。那我完全可以绕开数据库直接把 .xlsx 文件当成存储介质——读取时把文件解析进编辑器保存时把编辑器里的数据整体写回文件。这就是标题里说的免数据库直接调用 EXCEL 文件。1.2 文件即存储适合什么场景这套思路听起来省事但它不是银弹先把自己的使用场景说清楚你才能判断要不要照搬。适合的场景有几个共同点首先是人数少同时在线编辑的人不超过二三十个这决定了大家不会在一个密集时间窗口里疯狂写入其次是内网或者小范围使用网络条件可控不需要跨地域协作然后是数据量不大表格行数在几万行以内单文件几十 MB 封顶。这种需求在传统企业、学校实验室、项目组内部特别常见大家并不是要一个数据库系统只是想把原来传来传去的 Excel 收敛到同一个网页上。不适合的场景也很明显如果你要支持上百人同时编辑或者对审计日志、细粒度权限有硬性要求或者表格里每天要写入几十万行数据那不要用这个方案。文件即存储的本质是用最终覆盖代替事务合并并发一高就会出覆盖问题后面我会专门讲怎么尽量回避。2. 整体结构与核心依赖一条链路串起来2.1 前端luckysheet 负责编辑体验luckysheet 是国产开源的一款类 Excel 在线表格组件官方文档说它支持多种格式、公式、图表、数据透视等功能实际用下来日常的编辑、合并单元格、样式、公式、条件格式这些都没问题界面和交互逻辑跟 Excel 非常接近用户不需要重新学习。我选它而不是其他表格库核心就三点第一是社区版免费MIT 协议二次开发没有授权顾虑第二是 API 足够简单官方封装了创建实例、获取全部 Sheet 数据的方法前后端衔接成本低第三是部署零负担它就是一堆静态文件只需要一个静态服务器把它跑起来不需要单独安装任何运行时框架。前端只需要引几个 JS/CSS 文件然后调用luckysheet.create()就能把一个空表格渲染出来这对接下来的项目结构很友好。2.2 后端Node.js SheetJS 负责读写文件后端我选了 Node.js 加 Express配合 SheetJS 社区版库npm 包名是xlsx来做 Excel 文件的解析和生成。选 Node 的原因很简单跟前端同一门语言处理 JSON 天然顺畅而且手头这台 Windows 机器本身就有了 Node 环境RUNme 脚本可以直接调用。SheetJS 是读写字幕 xlsx 文件的事实标准库它能解析 Excel 文件里的工作表、行列单元格、合并区域也能把二维数组转换成工作表再写回 xlsx。这里有一个很重要的点SheetJS 社区版不支持样式解析也就是单元格的字体、颜色、背景色这些信息读写之后会丢。所以我在设计的时候就明确告诉使用者这个工具承担的是内容协作职责不是像素级复刻原文件职责。如果原始 Excel 里有大量复杂样式打开后肯定会变样这一点必须提前跟业务方对齐否则会被当成 Bug 投诉。2.3 数据流的三种状态整个系统里数据有三种形态理清这三种形态后面的代码就顺了。第一种是磁盘上的 .xlsx 物理文件它是一切数据的源头第二种是 luckysheet 编辑器内部的 JSON 数据结构它描述了一个工作簿里有哪些 Sheet、每个 Sheet 的行列、单元格值、合并信息第三种是后端做转换时的二维数组中间态SheetJS 读写 Excel 时最常接受这种格式。用户打开页面时后端把 .xlsx 读出来转成第二种 JSON 结构交给 luckysheet 渲染。用户在网页上编辑时数据只存在于前端内存里不会立刻写文件。每隔 60 秒前端把当前的第二种 JSON 数据 POST 到后端后端把它转回第一种 .xlsx 文件覆盖保存。整个链路里没有任何数据库数据只在一个方向流转文件 → 编辑器 → 文件。3. 核心实现Excel 加载、回写与60秒自动保存3.1 项目骨架与依赖安装先看目录结构和依赖这个项目精简到只有三个核心文件excel-collab/ ├── public/ │ └── index.html # luckysheet 前端页面 ├── data/ │ └── 团队协作表.xlsx # 要读取和写入的 Excel 文件 ├── server.js # Express 后端提供页面和保存接口 ├── RUNme.bat # Windows 一键启动 └── RUNme.sh # macOS/Linux 一键启动后端只需要两个依赖express和xlsxpackage.json写清楚版本就行。安装时用国内镜像会快很多npm install express xlsx --registryhttps://registry.npmmirror.com启动时机是先在data/下放一个.xlsx文件名字可以自己定然后把主文件路径写进server.js顶部的常量配置里。服务跑起来后后端会先把文件里所有 Sheet 解析成 luckysheet 能识别的结构再通过页面接口吐给前端前端拿到后调用luckysheet.create()渲染。整个流程非常短适合不懂前端的读者往下跟。3.2 Excel 怎么加载进编辑器这是整个项目里最容易写错的地方因为我最初想当然地以为把 xlsx 数据原样塞给 luckysheet 就行结果页面白屏。后来看文档才发现两者数据结构不一样必须做一层转换。SheetJS 读文件后拿到的是Workbook对象我重点用两个东西wb.SheetNames拿工作表名字列表wb.Sheets[sheetName]拿具体工作表。要把一个工作表转成 luckysheet 的data二维数组我写了一个转换函数const XLSX require(xlsx); function sheetToLuckysheetData(ws) { // header: 1 表示把工作表转成二维数组不把第一行当表头 const rows XLSX.utils.sheet_to_json(ws, { header: 1 }); const data []; for (let r 0; r rows.length; r) { if (!data[r]) data[r] []; for (let c 0; c rows[r].length; c) { data[r][c] { v: rows[r][c] }; } } return data; }这里有几个很实用的细节。rows[r][c]原始值可能是字符串、数字、日期、公式等luckysheet 的统一格式是{ v: 值 }所以要把每个格子包一层。空行和空列不需要补到满二维数组是稀疏的也没关系因为 renderer 会自己处理。公式值直接放进v就行luckysheet 看到v字段以等号开头会把它当成公式重新计算。但真正让我抓狂的是合并单元格。Excel 里的合并区域存在工作表的!merges属性里luckysheet 却不认识这个属性它有自己的合并配置长这样config { merge: { // key 是 起始行_起始列 0_0: { r: 0, c: 0, rs: 2, cs: 3 } } }意思是第 0 行第 0 列开始向下合并 2 行、向右合并 3 列。所以读文件时要把!merges循环一遍转换 key 的格式function parseMerges(ws) { const merge {}; if (ws[!merges]) { ws[!merges].forEach((m) { const key ${m.s.r}_${m.s.c}; merge[key] { r: m.s.r, c: m.s.c, rs: m.e.r - m.s.r 1, cs: m.e.c - m.s.c 1 }; }); } return merge; }最后组装成 luckysheet 能识别的 sheet 对象const sheets wb.SheetNames.map((name, idx) ({ name, index: idx, data: [sheetToLuckysheetData(wb.Sheets[name])], config: { merge: parseMerges(wb.Sheets[name]) } }));这里data注意要包一层数组表示这是整个 sheet 的数据集。这个结构我调了两版才跑通经验就是多看官方的接口说明别凭感觉猜格式。3.3 60 秒自动保存定时器、脏标记、保存锁前端拿到 sheets 数据后初始化编辑器luckysheet.create({ container: luckysheet, title: 团队协作表, data: sheets, // 后端转换好的结构 column: 26, row: 200 });自动保存逻辑的关键不是每 60 秒无脑保存一次而是讲究策略地保存否则会觉得卡顿。我用了一个脏标记 定时器 保存锁的组合。首先定义一个dirty标志luckysheet 的updated事件会在内容真实变化时触发我把dirty置为true。然后开一个 60 秒的定时器每次触发时检查dirty如果是true才发保存请求发完立即把dirty重置为false。这样没有修改的时候文件不会被反复无意义地覆盖。保存锁是为了防止上一次保存还没完成下一次定时器又触发了。我用一个布尔变量isSaving请求开始置true返回或报错后置falsesetInterval(() { if (!dirty || isSaving) return; const allSheets luckysheet.getAllSheets(); fetch(/api/save, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ sheets: allSheets }) }).then(() { dirty false; isSaving false; }) .catch(() { isSaving false; }); isSaving true; }, 60 * 1000);后端/api/save接口把sheets数组转回 xlsx 文件。这个转换是前面过程的逆操作每个 sheet 的data[0]是二维数组先把每个格子的v字段提取出来得到二维数组再用XLSX.utils.aoa_to_sheet()转回工作表。合并配置也别忘了还原app.post(/api/save, (req, res) { const sheets req.body.sheets; const wb XLSX.utils.book_new(); sheets.forEach((sheet) { const rows sheet.data[0].map(row row.map(cell cell ? cell.v : null)); const ws XLSX.utils.aoa_to_sheet(rows); // 合并信息还原成 !merges if (sheet.config sheet.config.merge) { ws[!merges] Object.values(sheet.config.merge).map(m ({ s: { r: m.r, c: m.c }, e: { r: m.r m.rs - 1, c: m.c m.cs - 1 } })); } XLSX.utils.book_append_sheet(wb, ws, sheet.name); }); XLSX.writeFile(wb, XLSX_FILE); res.json({ ok: true }); });这里再提醒一句保存一定要先写临时文件再替换目标文件。我最初直接writeFile覆盖目标路径结果有一次保存过程中机器断电原文件直接坏了。后来改成writeFile到同一个目录下的临时文件再用fs.renameSync原子替换再也没坏过文件。临时目录遗留文件定期清理即可。4. RUNme 一键启动是怎么设计的4.1 一键启动脚本要解决的问题标题里写了解压直接运行 RUNme这是整个项目体验的关键。设计这个脚本的时候我给自己定了个目标让一个完全不懂命令行的同事也能启动服务。这意味着脚本要自动做完三件事第一检查电脑上有没有 Node.js 环境第二首次运行自动安装依赖第三准备好数据目录并启动服务。如果这三件事都让使用者手动做那这套免数据库方案的价值就少了一大半。手动装依赖、敲命令这些步骤对程序员是家常便饭但对大多数人就是门槛。所以我把所有能自动化的步骤全都塞进了脚本里用户唯一要做的就是双击。4.2 Windows 与 macOS/Linux 两版脚本Windows 环境我用批处理脚本这是最老土也最通用的方式任何 Windows 机器都能直接双击运行echo off chcp 65001 nul cd /d %~dp0 where node nul 2nul if %errorlevel% neq 0 ( echo [RUNme] 未检测到 Node.js请先安装 Node.js 16 或更高版本 pause exit /b 1 ) if not exist node_modules ( echo [RUNme] 首次运行正在安装依赖... npm install --registryhttps://registry.npmmirror.com ) if not exist data mkdir data echo [RUNme] 启动中浏览器将自动打开 http://localhost:3000 start http://localhost:3000 node server.jsmacOS/Linux 用户会用到 shell 脚本逻辑完全一致只有自动打开浏览器的命令不同#!/bin/bash cd $(dirname $0) if ! command -v node /dev/null; then echo [RUNme] 未检测到 Node.js请先安装 Node.js 16 exit 1 fi [ -d node_modules ] || npm install --registryhttps://registry.npmmirror.com [ -d data ] || mkdir data open http://localhost:3000 2/dev/null || xdg-open http://localhost:3000 2/dev/null || true node server.js有一点我第一版做漏了server.js里如果用相对路径读文件脚本必须在项目根目录执行才行否则会报文件不存在。所以脚本开头第一行用法必须写cd /d %~dp0或cd $(dirname $0)强制把当前目录切到脚本所在目录。这个一行代码解决的问题当时让我排查了整整二十分钟运行路径问题在 Node 项目里太常见了。4.3 首次运行会碰到的环境和端口问题实际给同事部署时我碰到过三类环境相关的问题。第一类是电脑上根本没有 Node.js双击后会黑屏闪退没有任何提示。所以脚本里where node探活那一段一定要保留并且用pause让窗口停留否则报错信息一闪而过使用者只会觉得双击没反应。后来我在少数几台机器上还遇到过 Node 版本太老的情况luckysheet 本身对版本要求不高但 Express 新版依赖 Node 16脚本里加一个版本提示更稳妥。第二类是端口占用。如果 3000 端口已经被别的程序占用Node 启动会报EADDRINUSE。我在server.js里加了一个自动换端口的逻辑监听失败就尝试 3001、3002直到成功然后控制台打印出实际地址。这个改动表面上不起眼实际用起来明显提升了大伙儿的信心。第三类是杀毒软件误报。Windows 系统有时候会把不认识的新脚本和临时文件判断为风险行为导致写入 data 目录失败。解决办法是让使用者把项目目录加入信任区或者把节点进程加白名单一般内网办公电脑安全软件都能设置。这个问题不是代码能完全解决的但提前在文档里写清楚能少接很多求助电话。5. 用了一段时间后我踩过的坑和优化建议5.1 文件覆盖写坏的教训以及接下来的备份策略文件覆盖写坏这个问题前面提过一嘴但我想再单独拿出来说因为它是整个项目里最严重的一次故障。有一天同事跟我反馈说表格打开是空的我上服务器一看data 目录下那个 xlsx 文件大小变成了 0 字节。排查半天发现是保存过程中机器突然重启文件写到一半没写完原文件被截断。从那以后我把保存逻辑改成了临时文件 原子替换并且加了一个自动备份机制每次保存前先把当前文件复制一份到data/backup/目录按时间戳命名只保留最近 10 份。这样即使新的保存把文件写坏了也能从备份里找回几分钟前的版本。这个备份策略成本极低但给这个免数据库方案补上了最后一块安全短板。5.2 多人同时编辑的覆盖风险怎么尽量回避文件即存储方案最大的天然缺陷就是多人同时编辑时会出现后写覆盖先写。两个人同时打开同一份表格A 改了第一行B 改了第二行A 先保存B 后保存B 把整个文件覆盖掉A 的修改就丢了。这个问题在早期使用中是真实发生过的。我的应对策略分两层。第一层是使用习惯层面我在前端页面上加了一个横幅提示显示当前在线人数并提醒多人同时编辑时请避免同时改同一区域。第二层是技术层面在 luckysheet 里禁用了单元格锁定之外的一些并发敏感操作把allowUpdate选项关掉不让前端自动做基于数据的实时协同。如果你真的需要多人实时协同要做冲突合并那必须上类似操作日志、协同算法这类东西那就超出这个免数据库方案的范畴了需要换架构。5.3 那些打开后变样的 Excel 特性需要提前说清楚使用中最容易引发不满的其实是格式兼容问题。有同事拿了一个特别复杂的 Excel 进来里面有数据透视表、图表、条件格式、冻结窗格、批注打开后发现透视表和图表不显示批注也不见了各种色块也没了。这种变样不是 luckysheet 的问题而是 SheetJS 社区版能力边界决定的——它主要解析值和结构复杂对象和样式一概不支持。我的建议是上线前做一次格式摸底把团队里常用的 Excel 文件类型列出来逐一测试转换效果。如果你的使用场景是数据录入和基础表格协作完全没有问题如果重度依赖图表和数据透视表这个方案就满足不了需要评估 luckysheet 官方也有的一些进阶方案或者直接考虑商业表格产品。还有一个容易被忽略的点是保存回 .xlsx 后你再用桌面版 Excel 打开有些在网页里看起来正常的单元格到 Excel 里可能会显示成科学计数法比如长数字、身份证号。我在转换函数里对纯数字做了判断超过 11 位的数字强制转成字符串再写入这个细节虽然小但直接决定了导出的文件能不能被别人正常使用。最后分享一个我个人的习惯不管自动保存做得多稳每周五下午我都会手动备份一次 data 整个目录打包放到另一个磁盘。这不是不信任代码而是这类文件即存储的项目整个系统的命脉就在这个文件夹里核心资产怎么强调备份都不过分。本文还有配套的精品资源点击获取
