Univer 部署指南从本地跑通到生产上线的完整路线【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univerUniver 是一个全栈、同构的办公 SDK能在浏览器和 Node.js 两端运行提供电子表格、文档和演示文稿的创建与编辑能力底层由 Canvas 渲染引擎、公式引擎和插件架构支撑。做 Univer 部署时最容易踩的坑集中在三处Node.js 与 pnpm 的版本门槛、开发/生产两套命令的差异、以及容器化后静态资源的路由和缓存问题。这篇指南按本地跑通 → 看懂架构 → 集成进产品 → 上生产 → 排查问题的顺序推进每一步都给出可直接执行的动作。先备好环境Node 22 pnpm 10Univer 对运行时有硬要求装之前先确认本机版本Node.js最低 20.0.0建议直接用 22.18 及以上。项目根目录package.json的devEngines里写死了22.18版本低了部分脚本会直接拒绝运行。pnpm建议 10.33.4 及以上它负责管理整个 workspacepackages/、presets/、examples/都在同一个 pnpm workspace 里。Git2.45.0 及以上即可。没有 nvm 的话先装一个版本管理器然后执行nvm install 22 nvm use 22 npm install -g pnpm10.33.4装完用node --version和pnpm --version各跑一遍确认两个版本号都在预期区间再进入下一步。本地快速跑通4 条命令# 1. 克隆仓库 git clone https://gitcode.com/GitHub_Trending/un/univer cd univer # 2. 安装全部依赖monorepo首次会比较久 pnpm install # 3. 启动开发服务器带 --watch改代码即热更新 pnpm dev启动成功后浏览器打开http://localhost:3002。注意端口不是常见的 3000examples/esbuild.config.mts里的逻辑是被占用就自动找下一个可用端口所以如果 3002 被别的进程占了终端打印的实际地址会往后顺延以启动时输出的 URL 为准。打开后你会看到一个多工作表、多实例的演示界面examples/目录下还有 docs、slides、sheets-multi、sheets-mobile 等一堆入口pnpm dev默认拉起的是 demo 入口如果只想要最小验证装完依赖后先跑一条pnpm typecheck底层走turbo typecheck全绿说明依赖树和工作区链接都没问题。花 10 分钟看懂结构后面集成不迷路Univer 的架构分三层核心逻辑模型、命令、服务、渲染Canvas 引擎、UI 交互菜单、快捷键、React 组件。核心原则是同构——Node.js 端支持度与浏览器同等优先。两条对你集成最有用的规则功能拆成两个插件底层逻辑放sheets-xxx模型、命令、服务界面放sheets-xxx-ui菜单、React 组件、Canvas 元素。比如筛选功能就是sheets-filtersheets-filter-ui这一对。依赖fs、path这类 Node API 的代码必须单独放 Node 专属插件里别混进能跑在浏览器的包中。对外只走 Facade APIFacade 是为浏览器和服务器两端共同设计的统一入口通过univerjs/presets组合而成。你在业务代码里操作表格数据时用 Facade 而不是直接调内部服务将来升级版本才不容易被内部实现变化绊住。想深挖某一块仓库里有一份 tldraw 白板格式的架构说明需要 tldraw 打开值得读的是这几份docs/tldr/object-architecture-design .tldr对象模型、docs/tldr/formula-engine-architecture.tldr公式引擎、docs/tldr/web-worker-architecture.tldrWeb Worker、docs/tldr/permission.tldr权限。同构开发约束的正式说明见 docs/ISOMORPHIC.md。集成进自己的产品用 presets 懒加载如果你的目标是在自己应用里嵌一个表格推荐的集成路径是以examples/里的入口为模板挑最接近你场景的抄纯 TS 无框架看preset-sheets-core需要文档能力加preset-docs-core。只注册用到的 preset别把所有univerjs/preset-*都塞进去——每个 preset 都是一组插件的打包全引会让首屏 bundle 大得没必要。重的功能插件用动态import()按需加载例如公式引擎// 需要用到公式功能时才加载避免拖慢首屏 const { UniverFormulaEngine } await import(univerjs/engine-formula);仓库根目录还内置了两个省事命令React 项目想降级/升级时可以试试pnpm use:react16和pnpm use:react19会调用scripts/react-version-manager.mts自动切换相关依赖版本。上生产一条构建命令 多阶段 Docker生成生产产物pnpm build:demo这条命令走examples/下的 esbuild 配置产物输出到examples/local目录是一个纯静态站点。pnpm build不带:demo是另一个东西——它构建的是packages/和presets/下的所有源码包只有你要改 Univer 本身、发自己的包时才需要。用 Docker 部署两阶段把镜像压小# 第一阶段装依赖 编译 FROM node:22-alpine AS builder WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN npm install -g pnpm10.33.4 RUN pnpm install --frozen-lockfile COPY . . RUN pnpm build:demo # 第二阶段只把产物拷进 nginx FROM nginx:alpine COPY --frombuilder /app/examples/local /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80关键动作是--frozen-lockfileCI 场景必须防止 lockfile 漂移和第二阶段只拷examples/local——最终镜像里没有 Node 运行时体积能小一大截。nginx 配置只需要抓住三件事SPA 回退、静态资源长缓存、gzipserver { listen 80; root /usr/share/nginx/html; index index.html; # 前端路由回退 location / { try_files $uri $uri/ /index.html; } # 静态资源长缓存 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control public, immutable; } gzip on; gzip_vary on; gzip_min_length 1024; gzip_types text/plain text/css text/xml text/javascript application/javascript application/json; }部署完先手动验证curl -I http://你的域名看状态码再刷新一次页面确认index.html走的是回退而不是 404。出了问题先查这里按现象 → 一句怎么办的格式列几个高频问题内存持续增长、页面越用越卡用pnpm dev:e2e起 E2E 模式的 demo在 Chrome DevTools 里执行E2EControllerAPI.loadAndRelease()反复创建/销毁工作簿看堆快照里Workbook实例是否被回收。常见元凶和修法整理在 docs/FIX_MEMORY_LEAK.md包括忘记销毁订阅、单例服务里订阅了当前工作簿等。构建/安装失败依赖冲突先pnpm store prune清理本地存储缓存再重装仍失败再怀疑 lockfile。改了代码页面不刷新热更新失效检查 3002 端口是否被残留进程占着杀掉后重启pnpm dev。某个功能模块没生效检查插件注册顺序以及逻辑包和 UI 包是否成对引入只装sheets-xxx不装sheets-xxx-ui时菜单和界面都不会出现。性能上给个粗略参照基础表格场景浏览器端内存大致在 50–100MB 量级复杂公式和大数据集会到 200MB 甚至更高多实例并存时继续叠加。数字只作量级参考上线前务必用你自己的真实数据压一遍。测试兜底三层各跑一遍单元测试pnpm test底层是turbo test -- --passWithNoTests跑各包的 Vitest 用例要覆盖率报告就换pnpm coverage。端到端pnpm test:e2e走 Playwright验证真实浏览器里的交互流程。视觉回归e2e/visual-comparison/下有整套截图对比用例docs/、sheets/两个子目录改了渲染代码后跑一遍diff 图能直接告诉你哪块渲染变了。最后补一句安全侧的动作定期跑pnpm audit看依赖漏洞生产环境给页面配 CSP 头敏感数据链路启用 TLS。这些不是 Univer 特有的事但嵌入办公类内容的应用尤其该做。收尾按你的场景选路线只想本地看一眼效果 → 环境那节 4 条命令20 分钟。要集成进产品 → 加上看懂结构和presets 懒加载两节。要上生产 →pnpm build:demo 多阶段 Docker nginx 三件套。要长期维护 → 把三层测试挂进 CI内存问题按 E2E 堆快照的方法定期巡检。别跳过验证步骤直接放量先在测试环境用真实数据把内存和并发过一遍再从小范围用户开始扩。【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考