本章你将学会分清三种产物dev开发时、dist构建产物、bundle安装包看懂npm run build的两步先vue-tsc查错再vite build装箱逐行读懂src-tauri/tauri.conf.json——软件出生证明上的每一栏亲手打出安装程序装到另一台电脑或另一个用户账户上验证学会备份学习记录复制一个 json 文件就能把大脑搬走需要的前置章节第 1 章Tauri 盒子、第 5 章Vite、第 6 章跑起来、第 13 章数据存哪对应项目文件package.json、src-tauri/tauri.conf.json、src-tauri/Cargo.toml、dist/27.1 从一个场景开始软件做完那天小雅说“我想让我表哥也用上他在另一个城市电脑里没有 Node、没有 VS Code只有浏览器都装不利索。”你发现问题了现在 EngFlow 只在你这台电脑、这个开发环境里活着——离开npm run tauri dev这条命令它就不存在。可是软件的本领恰恰是离开作者也能活拷进任何一台 Windows 电脑双击图标就能用。从我电脑上跑着的代码到别人电脑上双击的程序中间隔着一步叫打包发布build bundle。这一步有三道关卡每道都有自己的产物新手最容易搞混源码菜谱 ──npm run build──▶ dist标准化的成品菜 ──npm run tauri build──▶ 安装包带饭盒的菜端走就能吃本章把三道关卡全走一遍顺便处理发布路上两件最容易出的事故改错 identifier 数据失踪和dev 正常 build 白屏。先做一个小预言走完本章你来对答案打包成功后你会得到两个都能双击安装的文件.msi和.exe很多人以为它们是同一个东西的两种皮肤——不完全对它们内部其实是两套不同的安装机制而你装完之后全世界会同时存在三份 EngFlow安装包送人的外卖、Program Files 里的程序饭店、%APPDATA%里的数据你打包带走的剩菜。三份里只有第三份是你的。这个三份论会在 27.4 和 27.6 反复救你的命。【配图说明三段流水线。第一段画源码文件夹进vite烤炉出 dist 盒第二段画 dist 进Tauri饭盒出 msi/exe第三段画一个 U 盘把 exe 递给别人】27.2 原理dist 是什么bundle 又是什么第一关npm run build——检查 装箱打开package.jsonscripts 里那一行你可能早就眼熟第 5 章见过一面build:vue-tsc --noEmit vite build它是两个命令用串起来的前一个成功了后一个才执行。像机场安检vue-tsc是安检员vite build是登机口。vue-tsc --noEmitTypeScript 检查器第 12 章的老朋友。它把全部.ts/.vue里的类型重新审一遍——有没有把string塞进number、有没有访问不存在的字段——只报告不产出文件--noEmit的意思就是别输出查完拉倒。为什么发布前非要过这道安检因为 dev 模式下 Vite 是用到才翻译有些从没被点到的页面类型错误会一路潜伏而运行时的小毛病可能悄悄写坏数据。发布版要给所有人用必须全量体检一次。vite build把散在src/里的几十个文件编译、压缩、合并成dist/里少数几个上线专用文件。跑完之后我们在项目里实测的输出真实数字vite v8.3.1 building client environment for production... ✓ 54 modules transformed. rendering chunks... computing gzip size... dist/index.html 0.49 kB │ gzip: 0.35 kB dist/assets/index-B5L7jvuz.css 41.59 kB │ gzip: 8.54 kB dist/assets/dist-js-BAnW1I5v.js 3.36 kB │ gzip: 1.24 kB dist/assets/index-ob2WvhM4.js 142.37 kB │ gzip: 55.58 kB ✓ built in 711ms三个看点每个文件跟着两列大小前一个是文件实际大小后一个gzip是网络打包后的大小——浏览器传输前会先压一遍。主程序 js 142.37 kB压完只剩 55.58 kB压缩比接近 3:1。0.71 秒、54 个模块我们的全部 Vue 源码被炼成一个 142 kB 的 js——第 7 章那些组件在产物里已经没有了文件边界全成了函数。dist/里还有一个 1.95 MB 的gre-bank.json——注意它没出现在上表里因为它不走打包是public/目录原样复制过来的静态资源。还记得第 19 章的懒加载吗词库故意不进主包软件一打开只下 55 kB等用户真去背 GRE 词时才取那个 1.95 MB。构建输出再次印证了设计——这是读构建日志的乐趣。顺便建立一把大小感觉尺55.58 kB 是什么概念一张手机照片大约 2000 kB——EngFlow 的整个主程序比一张照片还小四十倍。CSS 那 8.54 kB 是第 2 章三件套里衣服的全部家当。而 41.59 kB 的 css 压到 8.54 kB压缩比接近 5:1——样式表里全是重复的颜色名和属性名gzip 最爱这种重复话。以后看到构建日志先问两个问题大的东西该不该大小的东西为什么小能回答这两问你就在读构建而不是跑构建。vue-tsc 万一拦下错误怎么办别慌它的报错格式第 5 章见过世面文件路径、行号、期望类型 vs 实际类型三行定罪。九成报错长得像你把 string 塞给了 number——第 12 章练习题里的老熟人。修它重新 build不修好dist 不会更新Tauri 也不会替你打包一份没通过安检的菜。第二关npm run tauri build——套上 Rust 饭盒dist/是一套网页文件双击dist/index.html也就能开个网页没有桌面图标、没有窗口标题栏设置、卸载也不干净。差的就是那层盒子。npm run tauri build干的事把tauri.conf.json里配置的窗口、图标、产品名交给 Rust 编译器编译出一个真正的 Windows 程序再把dist/整个塞进 exe 肚子里——最终产物是安装程序双击安装后开始菜单有图标、卸载面板有名字、数据有专属目录。所以三层关系一句话钉死dev 是厨师边炒边尝dist 是炒好的菜bundle 是装盒贴标的外卖。送人永远送盒子。再把 dev 和 build 的差别摆成一排以后见到dev 行 build 不行的事故这一排字就是诊断手册npm run dev试吃npm run build出餐谁在跑代码Vite 开发服务器localhost:1420现场翻译提前全部编译好的静态文件改一行代码立刻热更新必须重新 buildTypeScript 类型错可能照跑不误先被 vue-tsc 拦下import 路径大小写Windows 下宽容严格错了就找不到绝对路径引用本机碰巧能通到别人电脑上必断体积不关心本机关心所以有 gzip 数字一句话读表dev 的环境处处偏向你build 的世界只尊重规则。这就是 27.6 节白屏事故的总根源。27.3 回到 EngFlow逐项精读 tauri.conf.json软件的出生证明就一页纸src-tauri/tauri.conf.json。全文 39 行我们分三块逐栏读。块一身份证区{$schema:https://schema.tauri.app/config/2,productName:EngFlow,version:0.1.0,identifier:com.engflow.app,productName产品名。决定窗口标题、安装包文件名、控制面板卸载列表里显示什么。version版本号含义见 27.5 小课堂。identifieridentifier 是软件的身份证号全世界它必须唯一格式约定像倒写的网址com.公司名.软件名。这一栏是整张证明上唯一 dangerous 的格子因为操作系统按它给软件分抽屉EngFlow 的学习数据存在C:\Users\你\AppData\Roaming\com.engflow.app\engflow.json改了 identifier 换一个新抽屉软件从此去新抽屉存取旧抽屉里的心血原封不动但再也看不见。27.6 节的惊魂事故就在这一格。顺便认一认抽屉家族——以后你在电脑里找各种软件的数据都按这张地图找%APPDATA% ( C:\Users\你\AppData\Roaming) ← 漫游区软件的主要数据。EngFlow 的家 %LOCALAPPDATA% ( ...\AppData\Local) ← 本地区缓存、临时件体积大、不跟着账户漫游Windows 给每个账户准备这两个平行区域Tauri 的 plugin-store 默认把engflow.json放进了漫游区的 identifier 文件夹里。有的软件还会多开一层子文件夹比如数据存储\规矩都一样identifier 在哪数据就在哪。另外那一行$schema也别忽略它指向官方说明书告诉编辑器这个 json 该有哪些栏、什么类型。有它在你改配置时 VS Code 会给你补全和红线提示——让机器帮你检查配置永远比肉眼靠谱这是全书反复出现的习惯还记得 tsconfig 吗同一招。块二建造流程区build:{beforeDevCommand:npm run dev,devUrl:http://localhost:1420,beforeBuildCommand:npm run build,frontendDist:../dist},四行两对恰好对应第 1 章说的盒子里住着一个浏览器开发时tauri dev盒子先替你跑npm run dev然后窗口去加载http://localhost:1420——对端口 1420 的老熟人原来登记在这里。发布时tauri build先自动跑npm run build安检装箱再去../dist取成品塞进安装包。这就是为什么你从没手动跑过 buildtauri build 也能产出新界面——beforeBuildCommand替你跑。块三窗口与出厂包装区app:{windows:[{title:EngFlow · 英语学习工作台,width:1200,height:800,minWidth:900,minHeight:620,resizable:true,center:true}],security:{csp:null}},bundle:{active:true,targets:all,icon:[icons/32x32.png,icons/128x128.png,icons/128x1282x.png,icons/icon.icns,icons/icon.ico]}}窗口打开时 1200×800minWidth/minHeight是缩得最小也不能更小的底线——再小卡片按钮就会挤成一团。center: true让窗口在屏幕正中出生体面。security.csp网页安全策略我们暂时设为null全放行。EngFlow 不联网、不加载远程脚本风险面极小等第 28 章真要接 AI 接口时这一格值得重新审查——把它记进已知待办这正是第 26 章教的习惯查过、暂不动、写下来。bundle.targets: all给每种该平台能吃的格式都出一份——Windows 上是.msi和.exe两种安装包。icon五连32/128/1282x png 管窗口和任务栏.ico管 Windows.icns管 Mac——一套源图多尺寸输出各平台各取所需。这就是前面反复叮嘱图标别马虎的原因图标是软件的脸。【配图说明一张出生证明表单样式图三块区域用彩笔圈出身份证区productName/version/identifier、建造流程区build 四行、包装区app/bundleidentifier 格子画一个红色警示三角】27.4 动手时间打包、安装、搬家一条龙第 1 步dist 出炉2 分钟PS D:\WorkSpace\CET6\learnEnglishnpmrun build你会看到先是vue-tsc默默跑十几秒没有消息就是好消息有错误它会逐条列出行号然后 vite 打出 27.2 节那份大小表最后✓ built in 660ms左右。用资源管理器打开dist\index.html、assets 里三个带乱码后缀的文件、还有原样躺着的 gre-bank.json。那个乱码后缀值得解释一句index-ob2WvhM4.js中间那串ob2WvhM4是文件内容的指纹第 18 章哈希的又一次出场。内容变一个字指纹就换一撮字母内容没变指纹不变。为什么要这样浏览器会缓存旧文件如果文件名不变用户可能永远拿不到新版文件名一换浏览器见没见过必去服务器取新的。缓存和更新这对冤家全靠文件名里的哈希握手言和。所以记住dist/里的文件不要手动改也不要给同学发你手改过的 dist——永远发刚 build 出来的。顺带认识一位新朋友第一次 build 时日志里可能闪过dist-js-BAnW1I5v.js这样一个几 kB 的小块——那是 Tauri 的插件代码被自动代码分割code splitting出去了不常用的东西切成小包用到才加载主包因此瘦身。Vite 自己会做这个决定你一行配置都不用写。第 2 步套盒一次漫长的等待PS D:\WorkSpace\CET6\learnEnglishnpmrun tauri build你会看到屏幕开始滚动 Rust 的编译进度几十行、几百行持续好几分钟第一次甚至要 20-40 分钟——它正在把 Tauri 用到的上百个 Rust 库crate从网上下载下来一个字母一个字母地编译成机器码而且用的是release 全力度优化模式。这里要做一次耐心教育Rust 的 release 编译慢是这门语言的交易——它用编译期的漫长换运行期的飞快和安全第 1 章说过 Tauri 的盒子是 Rust 打的这就是盒子的工费。看到进度条爬得慢别慌、别强制关机去喝杯牛奶或者拿这二十分钟把 27.5 的备份先做了。第一次之后增量编译会快很多但每次改了 Rust 侧配置它还是会认真地重新烤。顺便参观一下工地src-tauri\里除了 tauri.conf.json还有Cargo.tomlRust 世界的 package.json——依赖清单管 Rust 盒子用哪些 crate、icons\源图五条 icon 配置的真实出处、capabilities\权限清单这个盒子允许网页侧调用哪些系统能力第 13 章 plugin-store 的读写权限就登记在这里以及编译时新建的target\——整个 target 都是 Rust 的厨房废料加半成品大到几个 GB 也随时可删和 dist 一样永远不进版本管理src-tauri\.gitignore里它就以/target/这一行在册。烤的过程中你会看到几百行Compiling xxx v1.2.3加一堆 warning——warning黄色警告不是 error红色错误warning 意思是能跑但我看着不对劲Rust 编译器是全书我们遇到的最啰嗦也最负责的安检员它连你写了个没用的变量都要提醒。红色的 error 出现时构建才会停而且它报得比 vue-tsc 还细照着小节建议改即可。第 3 步开盒验货烤完后去这里领产物路径里的版本号随version变src-tauri\target\release\bundle\msi\EngFlow_0.1.0_x64_zh-CN.msi src-tauri\target\release\bundle\nsis\EngFlow_0.1.0_x64.exemsi 和 exe 都是安装程序msi 偏单位统一装机学校机房管理员爱它可以用命令一次装五十台exe 双击安装更顺手发给朋友用后者。它们连进度条都是两套代码画的——这就是 27.1 预言里不是同一东西换皮肤的意思。挑一台干净电脑验证——没有装过 Node、没有这个项目的任何源代码的那台没有第二台就在自己电脑上新建一个 Windows 本地用户切换过去装。干净这两个字值千金你自己的开发机装着 Node、缓存着一切、路径里全是项目痕迹它在场测试就不算数。这跟第 1 章快捷方式、exe、源码三分是同一课——测试软件要测的是它离开你之后的样子。验收单四勾双击安装开始菜单出现EngFlow图标打开窗口标题EngFlow · 英语学习工作台初始大小 1200×800、拉到很小时在 900×620 卡住conf 生效收藏一个panda关掉再打开——还在数据写进了这台机器的新抽屉控制面板能正规卸载卸载后%APPDATA%\com.engflow.app还保留着数据卸载删程序、不删学习记录这是为用户负责呼应第 1 章符号、本体、原料三分。四勾全过之后再加三个出厂三问问体积安装完 Program Files 里多大几十 MB——别忘了 exe 肚子里揣着整个 dist1.95 MB 的词库也在其中。问数据新装的软件在%APPDATA%下建没建com.engflow.app没建说明没写到文件可能掉进了白屏但其实没启动成功的坑27.6 事故二。问图标桌面和任务栏的图标清晰吗发糊通常是 png 尺寸不全conf 的 icon 五连少了一栏。三问都答得上来这份 bundle 才算出厂。【配图说明一份三份论家谱图。顶端一个 exe 安装包画成外卖盒标注送人的装完就功成身退箭头指向中间 Program Files 里的饭店“程序本体卸载就拿走”再一个箭头指向第三份——%APPDATA% 里贴着封条的 engflow.json“你的学习记录唯一真正属于你的那份”第三条箭头描最粗旁边画一颗小星星】第 4 步备份你的学习记录——搬家带走大脑现在做发布章最重要的实操。你的全部学习记录——卡片进度、连续打卡、收藏的词、最近 60 天历史——就是第 13 章挖到的那个文件%APPDATA%\com.engflow.app\engflow.json地址栏粘贴%APPDATA%回车就到。备份只要一步PSCopy-Item$env:APPDATA\com.engflow.app\engflow.jsonD:\我的备份\engflow-$(Get-Date-FormatyyyyMMdd).json把副本放进网盘或 U 盘换电脑、重装系统之后把文件复制回原位启动 EngFlow——三个月的复习进度原地复活。原理第 13 章就学过软件只是菜谱数据才是你真正在用的东西菜谱随便重装数据必须备份。恢复是一门手艺练一遍才算会。现在就演练复制一份 engflow.json 到桌面 → 删掉原文件 → 打开软件它应该给你一份全新的空档→ 把桌面的副本放回去 → 再打开——panda 和全部打卡记录回来了。全程一分钟。没演练过的备份等于没有备份真到搬家那天你会在放回去之后会不会崩面前发抖。也建议每月把带日期的副本存进网盘一份——它比照片小一万倍却记录着你真金白银的时间。也可以直接把这个 json 发给另一台已装好的电脑导入自己实现导入界面是第 28 章的开放挑战之一。27.5 版本号小课堂0.1.0——三段数字学名叫语义化版本SemVer规矩是位置名字什么时候 1例句第 1 位0主版本大改产品脱胎换骨、老存档可能不兼容从背单词软件升级成学习平台 →1.0.0第 2 位1次版本新功能加了新页面、新字段老用户照常用上线语法模块 →0.2.0第 3 位0补丁修 bug只修问题不加功能修好连点丢分 →0.1.1我们停在0.1.0是有讲究的第一位是 0等于挂牌试用期——数据结构随时可能改请用户别把兼容性当承诺。等第 28 章把 Phase 4 做完、字段稳定了就该升1.0.0——那是软件的成年礼。记住口诀大改动第一位加菜动第二位补漏动第三位后两位归零规则升 0.2.0 时第三位必须回到 0顺手就懂了。版本号改哪儿两处要同时改少一处就会出现装的软件说自己是 0.1.0、安装包文件名写着 0.1.1的怪事package.json version: 0.1.0 ← js 世界这边 src-tauri\tauri.conf.json version: 0.1.0 ← Rust 盒子那边两处不一致时以tauri.conf.json为准——安装包名和关于页看的是它。所以养成习惯升版本一口气改两处第 26 章的两把尺子教训在版本号上完全适用。顺便把三件东西的分工钉牢这是本章的出厂三问归谁管什么时候动它productName: EngFlow给人看的名字标题栏/卸载列表市场说要改名改version: 0.1.0发布节奏大/中/小每次发布动对应位identifier: com.engflow.app数据的门牌号永不。它不属于改名自由它属于用户的数据最后一行请读两遍改名自由是程序的自由门牌号是用户的数据——程序没有权力动用户的门牌号。这也是为什么老软件可以改产品名却极少改 identifier那等于宣布全体失忆。27.6 小毛病大修理事故一改了 identifier 之后数据全没了惊魂 48 小时事故现场发布前夜同学看着com.engflow.app说不像个网址我改成com.engflow.desktop更工整。两分钟后他打来电话声音发抖我的词没了panda 没了报告全是零EngFlow 把我当新用户了软件是不是把数据删了”真相数据一个字节都没丢。第 27.3 节说过identifier 决定抽屉。抽屉名一改软件去com.engflow.desktop这个新抽屉找数据——当然是空的于是给你一份默认档三个月的心血好好地躺在旧抽屉com.engflow.app里睡大觉只是没人去开。新抽屉为什么是空的还记得第 13 章loadData()的剧本吗——拿不到数据不是错误是还没有数据软件会客客气气地发一份DEFAULT_DATA空卡片、空历史、空收藏继续运行。这个设计平时是优点新用户零配置即用惊魂夜成了吓人的帮凶它演得太像数据被删了。所以排查这种失踪案第一条线索永远是去%APPDATA%看一眼真丢了是没有文件的没丢文件安安静静躺在某个旧名字的抽屉里。空软件是空壳子旧壳一开满壳是宝。找回方法当时执行的完整步骤关掉软件打开%APPDATA%能看到两个抽屉并排com.engflow.app和com.engflow.desktop把旧抽屉里的engflow.json复制进新抽屉或者一劳永逸把 conf 里的 identifier 改回旧值启动——panda 回来了连复习到期日都分毫不差。立案规则identifier 是出厂即终身的一栏——它是地址不是装饰。以后任何重构、改名、换图标都别碰它真需要改名产品名可改identifier 必须保留否则等于要求所有用户集体失忆。这一条我们写进了项目备忘也请你写进自己的第一行发布纪律。事故二dev 一切正常build 之后白屏事故现场另一类经典——打包完的 exe 打开是一个纯白窗口dev 模式却好好的。白屏说明网页根本没跑起来两个最常见的原因路径大小写不一致代码里写import Dashboard from ./components/dashboard.vue实际文件叫Dashboard.vue。Windows 文件系统粗线条大小写不敏感dev 照样跑可vite build和 Linux 打包机是认真的人找不到dashboard.vue就把模块丢了运行时一碰面就白屏。教训一句话dev 是宽待你的老师build 是验收你的考官。资源用了绝对路径页面里写img srcD:/WorkSpace/.../cover.png或者fetch(http://localhost:1420/gre-bank.json)这类只有我这台机器才认的地址。dev 跑在你电脑上碰巧灵装到小雅表哥电脑上D 盘根本没有那个文件夹请求失败首屏脚本一崩全家白屏。正确姿势是相对路径加 publicfetch(gre-bank.json)我们的bank.ts就是这么写的。排查步骤四步定位法按顺序一步一刀第 1 步npm run preview —— 不走 Tauri本地 http 服务器直接开 dist 白屏→ 问题在 dist前端产物继续第 2 步 正常→ 问题在 Tauri 侧conf 的 frontendDist 指错dist 是旧的 第 2 步浏览器 F12 → Console 看红字、Network 看 404 404 的文件名大小写不对 → 原因 1404 的是外部绝对地址 → 原因 2 第 3 步修源码 → 重新 npm run build → 再 preview 确认 第 4 步最后才重新 tauri buildRust 侧没改动时它其实只重装箱第 1 步的npm run preview是本章最值得带走的一招它就是先尝一口再装盒不启动桌面软件、不等漫长的 Rust用浏览器直接看 dist 跑得对不对几秒钟出结论。能把大问题切成两半的工具永远比能解决大问题的工具更常用。90% 的dev 行 build 不行都栽在大小写和绝对路径这两个路径问题上。剩下的 10% 里最常见的是dist 是旧的——忘了重新 build 就 tauri build盒子里装的还是昨天的菜好在beforeBuildCommand这道自动流程让这类事故少了一大半但手动折腾过 dist 的人都懂。而第 1 步那招把盒子拆开单独验菜是通用思维产物独立验能一下子把网页的锅和盒子的锅分开——以后无论修什么软件先找到那条把大问题切成两半的缝。发布纪律最终浓缩成三句请抄在你项目的 README 末尾① identifier 终身不改② 版本号两处同改③ 每次发布前做一次 27.4 的恢复演练。27.7 本章你会解释dist 和 bundle 的区别是什么谁是最终送人的那份dist 是编译装箱好的网页文件bundle 是套上 Tauri 盒子的安装包送人用 bundlenpm run build里前后分别是谁谁失败了后面就不跑vue-tsc 安检 / vite build 装箱安检不过就不装箱identifier 是干什么的为什么永世不改软件身份证号决定数据目录改了换抽屉旧数据看不见学习记录备份要拷哪个文件、放在哪%APPDATA%\com.engflow.app\engflow.json版本号0.1.0里那个0在向用户承诺什么试用期数据结构还可能大改别当 1.0 依赖dev 正常 build 白屏两个常见原因是什么第一步排查命令是什么大小写路径 / 绝对路径资源npm run preview27.8 练习★ 热身填空合上书把三道关卡默写出来——源码 ──( )──▶ dist ──( )──▶ 安装包再默写数据文件的完整路径从%开始写。写不出就回 27.1 和 27.4这两处是本章的地基。★ 完整跑一遍npm run build把构建输出的大小表抄下来找出哪个文件最大它为什么没被 gzip 那几行列出gre-bank.json静态资源原样复制不走打包★★ 把 27.4 第 3 步的验收单四勾做成一张纸质清单请一位家人当验收员在打包版里逐项操作并签字。体验一下用户拿到的永远是最终产品你的环境帮不了他。★★★ 思考题如果两位用户各自改了engflow.json备份现在要把两份合并成一份会发生什么难处提示第 25 章——两份都改过的点名册谁覆盖谁这就是第 28 章多设备同步候选里最大风险一栏的答案预告。全书正文到这里就讲完了怎么做出来。但一个真正的工程师最后要回答的问题是接下来做什么。最后一章没有标准答案——那是留给你自己的毕业设计。