让模型处理表格,最容易出问题的地方不是它不会写代码,而是它交回来的东西「看起来对」。它给你一份 CSV,月份列写着 2026-07,你打开一看是 46204;它写了 =SUM(...) 却立刻读回来拿到 null 就报「任务完成」;它填第三千行时报错,因为它不知道默认的表只有 1000 行。这三件事我在同一个下午全踩了一遍,用的都是同一套工具:Univer 的开源 headless 模式。
Univer 是国内的 DreamNum 团队做的 Office SDK,昨天(11 月 16 日)刚发 v1.5.2,GitHub 上 27,797 star、Apache-2.0(star 数与发布时间都是我用 GitHub API 现查的)。11 月 17 日它在 GitHub 日榜前排,第三方日榜记录当日涨了 1,878 star。它的卖点不是「再做一个在线 Excel」,而是把表格的内容模型、命令系统、公式引擎拆成包,让你在 Node 里直接调用——没有浏览器,没有 Canvas,没有界面。
先说清楚哪些是开源的,哪些要钱
这件事决定你能拿它干什么,所以放在最前面:
- Web SDK(Apache-2.0,开源):内容模型、单元格读写、公式计算、快照保存。可以嵌到自己的网页编辑器里,也可以像我这样在 Node 里跑无头任务。
- Server SDK(商业授权):实时协作服务端、编辑历史、Office 文件导入导出。XLSX 的读和写在这一层,官方文档写得很明确:Office conversion requires Server SDK。
- AI SDK(商业授权):把 Office 能力接进已有 Agent 的工具层。
所以「用 Univer 替代 openpyxl 读写 xlsx」这个想法,在开源版上是走不通的。开源版给你的是一个活在内存里的、会算公式的工作簿,出入都得你自己接(CSV、数据库、JSON 快照)。想清楚这一点,后面的判断才不会跑偏。
装起来:七个包,纯 Node,147 毫秒
我这次的实测环境:macOS 26.5.2 / Apple M4 / 16GB,Node v22.22.2,npm 10.9.7,@univerjs/* 全部 1.5.2。安装 64 个包用了 9 秒。
# 建个空项目,类型必须写 module(这些包是 ESM 优先)
mkdir univer-lab && cd univer-lab
npm init -y
node -e "const p=require('./package.json');p.type='module';require('fs').writeFileSync('package.json',JSON.stringify(p,null,2))"
npm install @univerjs/core@1.5.2 @univerjs/engine-render@1.5.2 \
@univerjs/engine-formula@1.5.2 @univerjs/docs@1.5.2 \
@univerjs/sheets@1.5.2 @univerjs/sheets-formula@1.5.2 \
@univerjs/sheets-numfmt@1.5.2然后是初始化。这段代码来自官方 Headless 指南,我照抄跑通。末尾那几个 xxx/facade 的 side-effect import 是 API 的挂载入口,照抄别删——我试过删掉 sheets-formula/facade,setFormula 和计算都还正常(说明 core facade 已经带了主路径),但官方把它列成必需项,其它组合我没有逐个试,没有必要省这几行:
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { FUniver } from '@univerjs/core/facade'
import { UniverDocsPlugin } from '@univerjs/docs'
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'
import { UniverRenderEnginePlugin } from '@univerjs/engine-render'
import { UniverSheetsPlugin } from '@univerjs/sheets'
import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'
import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'
import SheetsEnUS from '@univerjs/sheets/locale/en-US'
import '@univerjs/engine-formula/facade'
import '@univerjs/sheets/facade'
import '@univerjs/sheets-formula/facade'
import '@univerjs/sheets-numfmt/facade'
const univer = new Univer({
locale: LocaleType.EN_US,
locales: { [LocaleType.EN_US]: mergeLocales(SheetsEnUS) },
})
univer.registerPlugin(UniverRenderEnginePlugin)
univer.registerPlugin(UniverFormulaEnginePlugin)
univer.registerPlugin(UniverDocsPlugin)
univer.registerPlugin(UniverSheetsPlugin)
univer.registerPlugin(UniverSheetsFormulaPlugin)
univer.registerPlugin(UniverSheetsNumfmtPlugin)
const univerAPI = FUniver.newAPI(univer)
univerAPI.createWorkbook({})
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()
sheet.getRange('A1:B3').setValues([['apple', 3], ['banana', 5], ['cherry', 7]])
sheet.getRange('C1').setValue('=SUM(B1:B3)')
sheet.getRange('C2').setValue('=B1*2')我原本以为 engine-render 在 Node 里会拉 DOM 或 canvas 依赖,实测纯 Node 直接跑通,不需要 jsdom 之类的补齐。冷启动也轻:@univerjs/core 首次 import 89ms,其余插件 58ms,合计 147ms——放进 serverless 也不会因为加载被打爆。
坑一:公式是异步算的,立刻读回来是 null
这是我第一个翻车点。写完公式马上读:
sheet.getRange('A4').setValue('=SUM(A1:A3)')
console.log(sheet.getRange('A4').getValue()) // null ← 不是 0,不是旧值
await new Promise(r => setTimeout(r, 100))
console.log(sheet.getRange('A4').getValue()) // 6拿到的是 null。它既不是 0,也不是报错,就是想让你以为这格是空的。原因是写操作走的是命令队列(mutation),公式计算在队尾,setValue 只是把命令排进去。任何「写完立刻读回来校验」的脚本都会在这里误判成失败,而这正是 Agent 生成代码最爱的写法——写完,读一下,打印「已验证」。
同一个坑还有第二种表现。我拿一个实例循环处理 200 轮报表,每轮清空、重写 100 行、加一条 =SUM,立刻读结果——200 轮全部 undefined,等到最后统一读,值是 4950,完全正确。也就是说:不会报错,不会警告,只有值是空的。
顺便说清 getValue 和 getRawValue 的区别,这个更要命:
// A2 存 1234.5678,并设置了货币格式 ¥#,##0.00
sheet.getRange('A2').getValue() // "¥1,234.57" ← 字符串!
sheet.getRange('A2').getRawValue() // 1234.5678
sheet.getRange('A2').getDisplayValue() // "¥1,234.57"getValue() 返回的是按数字格式渲染后的结果,不是数值。1/3 通过 getValue 读是 0.333333333333(12 位),getRawValue 才是 0.3333333333333333(快照里存的也是全精度)。做数据校验、回写数据库、二次计算,一律用 getRawValue()。用 getValue 的下场是把 "¥1,234.57" 当数字塞进下游,然后在下游的 float() 里炸掉。
坑二:默认的表只有 1000 行、20 列
createWorkbook({}) 出来的工作簿,getMaxRows() 是 1000,getMaxColumns() 是 20。Excel 是 1,048,576 × 16,384。我往第 5000 行写数据,直接抛 Range is out of bounds. Max rows: 1000, Max columns: 20——好在这条会抛错,比静默好。
改起来不麻烦,但顺序不能错:先扩容,再写数据。
sheet.setRowCount(20000)
sheet.setColumnCount(32) // 1ms,纯改元数据
sheet.getRange(0, 0, 5000, 5).setValues(bigData)值得记一笔的是这个默认值背后的设计取舍:Univer 是给「网页里嵌一个表格」设计的,默认小表更省内存和渲染开销。放到服务端跑批处理,这个默认值就是纯负担——你的第一批数据就可能超界。
坑三:日期样的字符串会被静默转成序列号(本节是重点)
这条我建议所有要做「AI 读表/写表」的人抄进笔记。Univer 的 setValues 会对字符串做类型推断,推断规则和 Excel 一致:像日期的就当日期,像数字的就当数字。
sheet.getRange('A1').setValue('2026-07') // raw = 46204, t = 2(数字), fmt = yyyy-mm
sheet.getRange('A2').setValue('2026-07-15') // raw = 46218, fmt = yyyy-mm-dd
sheet.getRange('A3').setValue('07/15/2026') // raw = 46218, fmt = mm/dd/yyyy(按美式解析)
sheet.getRange('A4').setValue('1-2') // raw = 46024, fmt = m-d ← 最阴的一条
sheet.getRange('A5').setValue('00123') // raw = 123(前导零没了)"1-2" 变成 46024,也就是 2026-01-02。一个产品型号、一个版本号、一个区间,只要长得像日期,就会变成某一天。更麻烦的是表面看不出来——数字格式被自动设成了 yyyy-mm,人在界面上看到还是「2026-07」,只有下游拿 raw 值时才炸。
我试了三种「应该管用」的写法,只有一种真的管用:
| 写法 | 结果 | 判断 |
|---|---|---|
先 setNumberFormat('@') 再 setValues |
仍被转成 46204,只是格式挂上了 @ |
✗ 无效 |
字符串加撇号 '2026-07(Excel 习惯) |
存成字面量 "'2026-07",撇号也进了值 |
✗ 更糟 |
setValueForCell({ v: '2026-07', t: 1 }) |
raw 返回 "2026-07",t=1(字符串) |
✓ 唯一正解 |
注意第三种的代价:它是逐格 API,不能像 setValues 那样一次灌一片。数据量大的时候只能循环,我测的单格写入大约 1ms 级别,几千行还能接受,十万行就得重新想办法(比如把这类列单独走一遍逐格写)。
Agent 场景里这条几乎必然踩:模型拿到 CSV 或用户口述的表格,最自然的写法就是 setValues 一把灌进去,日期列全变数字,然后它读回来一看「2026-07 变成了 46204」,再自作聪明地 TEXT() 一下,改成字符串「46204」——错两次。
端到端跑一遍:CSV 进,汇总出
光看 API 没意思,我写了个真实的小报表:9 行销售明细(月份、产品、渠道、金额),进 Univer 算六个指标,导出 CSV,再用 Python 独立算一遍对答案。
import fs from 'node:fs'
import { makeAPI, sleep } from './lib.mjs' // lib.mjs 就是上面那段初始化
const rows = fs.readFileSync('data.csv', 'utf8').trim().split('\n').slice(1).map(l => l.split(','))
const { api } = await makeAPI()
const wb = api.getActiveWorkbook()
const s = wb.getActiveSheet()
s.setName('明细')
s.setRowCount(rows.length + 12)
s.setColumnCount(8)
s.getRange(1, 0, rows.length, 4).setValues(rows.map(r => [r[0], r[1], r[2], Number(r[3])]))
const r0 = 2, r1 = rows.length + 1 // A2:A10
const summary = [
['指标', '值'],
['总营收', `=SUM(D${r0}:D${r1})`],
['订单数', `=COUNTA(D${r0}:D${r1})`],
['客单价', `=ROUND(SUM(D${r0}:D${r1})/COUNTA(D${r0}:D${r1}),2)`],
['直销占比', `=TEXT(SUMIF(C${r0}:C${r1},"直销",D${r0}:D${r1})/SUM(D${r0}:D${r1}),"0.0%")`],
['最大单笔', `=MAX(D${r0}:D${r1})`],
['9月营收', `=SUMIF(A${r0}:A${r1},"2026-09",D${r0}:D${r1})`],
]
s.getRange(0, 5, summary.length, 2).setValues(summary)
await sleep(1200) // 坑一:等计算
const out = summary.map((_, i) => {
const c = s.getRange(i, 6)
return [summary[i][0], c.getRawValue()] // 坑一:用 raw
})
console.log(out)跑出来的结果和我用 Python 独立核算的完全一致:
| 指标 | Univer 计算结果 | Python 独立核算 |
|---|---|---|
| 总营收 | 682,200 | 682,200 |
| 订单数 | 9 | 9 |
| 客单价 | 75,800 | 75,800 |
| 直销占比 | 75.9% | 75.9% |
| 最大单笔 | 141,000 | 141,000 |
| 9 月营收 | 236,700 | 236,700 |
但导出的 CSV 又给我上了一课:月份列全是 46204 这样的数字。原因就是坑三,我在这个例子里故意没修,好让对比清楚——同样的代码,加上 setValueForCell({ v, t: 1 }) 逐格写月份列,导出的 CSV 才是 2026-07。
公式引擎到底能算到什么程度
我把 34 条常用公式一次性写进一张表,等 1.5 秒后逐条读 raw 值:32 条结果正确,两条有问题。
算对的部分挺全:SUM/AVERAGE/MAX/MEDIAN/STDEV、COUNTIF/SUMIF/SUMPRODUCT、VLOOKUP/INDEX/MATCH/XLOOKUP、IF/IFERROR/LET、TEXT/TEXTJOIN/CONCATENATE/TRIM/SUBSTITUTE/LEFT、DATE/YEAR/RANK。错误值是标准写法:=B1/0 给 #DIV/0!,=B1+ 给 #VALUE!。跨表也正常,=VLOOKUP("k3",Sheet1!A1:B3,2,FALSE) 和 =SUM(Sheet1!B1:B3)+SUM(B1:B2) 都对。
有问题的两类:
- 动态数组不铺开,而且两次跑结果不一样:第一轮
UNIQUE对 4 个不同值给#SPILL!,SEQUENCE(3)也是#SPILL!;我单独复测时UNIQUE返回了第一个值"x",SORT返回排好序的第一格"w"(内部算对了,只是不铺开),TRANSPOSE稳定给#SPILL!。也就是说靠溢出填充整片区域的写法在这里不成立,而且失败方式还不统一——这种不统一比单纯不支持更难排查。 - 循环引用静默归零:A1=
=A2+1、A2==A1+1,两格都返回 0,没有#REF!,getFormulaError()也是空数组。Excel 会警告你循环引用,这里什么都不说。
对做「模型生成公式、我负责校验」的流程,这两条意味着校验不能只看「有没有报错」——没报错不等于算对了。
性能:够不够放进服务端
我在 M4 / 16GB 上量了几组数:
- 写 25,000 个单元格(5000×5):50ms
- 写 5,000 条公式:23ms;4 秒内全部算完,抽样值与手算一致
- 快照 79 万字符(约 793KB JSON),压缩后还会更小
- 同一进程连续建 50 个独立实例:657ms,RSS 稳定在 210MB
- 复用单实例跑 200 轮「清空→写 100 行→加公式」:中位 1ms,P90 2ms
结论挺清楚:一个进程按请求建实例是可行的(50 个实例 657ms 就建完,内存没涨),也可以单实例复用(单轮 1ms 级)。协作、持久化这些它不管,你得自己接。
我的判断:什么情况下用它,什么情况下别用
值得用的场景:
- 要给 Agent 一个「算表格」的工具。模型不需要自己实现公式解析,用 Univer 当执行层,你只负责把单元格值喂进去、把 raw 值取回来。这条链路我上面验证过,数字对得上。
- 自己的产品里要嵌表格编辑器。这是它本来的用途,开源部分(模型+渲染+公式)够搭一个像样的编辑器内核。
- 服务端批量算表。比起用 openpyxl 算不了公式(它只读写,不算),Univer 是真的会算。
不适合的场景,也说清楚:
- 要做 xlsx 保真往返。开源版不可以,Server SDK 是商业授权,这部分我没有可用授权,未实测。真需要,现成方案是 SheetJS 读写 + 自己维护公式,或者直接用 LibreOffice 无头转换。
- 要跟 Excel 完全一致的计算结果。动态数组、循环引用检测、精度口径这三处已经能看出差异,财务级核对要慎用。
- 要图表、要截图。文档明说图表数据能改但不渲染,截图需要渲染运行时。
- 超大数据量。我只测到 25,000 格,更大的规模没有测,不要拿我的数字外推。
收尾:表格是 Agent 最容易「假装成功」的地方
把这次踩的坑排一下顺序,我觉得对做 AI 表格的人最有用的顺序是:类型推断(数据被改)> 异步计算(结果是空)> 默认尺寸(写不进去)。第一条最危险,因为它不报错、界面上还显示得挺对;第二条最容易被 Agent 误判为失败;第三条最好查,因为会直接抛异常。
Univer 这个项目本身是扎实的,公式引擎的水平不是玩具级,headless 模式也确实不需要浏览器。它的问题不在能力,在默认值:为网页编辑器设计的默认值(小表、自动类型推断、显示口径取值),放到「机器写表」的场景里全都是坑。这也算是给做 Agent 工具的人提个醒——给模型用的 API,默认值该按「机器」调,不该按「人」调。顺带一提,之前测 opencode 共享服务端时也是同一类问题:工具本身没毛病,默认假设和你的用法不匹配。
下一步我打算拿它接在 OCR 出来的长文档表格后面:先把扫描件的表抽成 CSV,再灌进 Univer 算汇总,让整条链路都不用开 Excel。服务端那层可以照 Flask 起个接口包起来;如果你已经在用 LoopForge 那类 SOP 编排,这段脚本正好放在 Script 节点里——确定性的活交给确定性代码,token 花在判断上。