前端Tauri打包规范书

前端Tauri打包规范书一、打包环境配置规范1.1基础环境要求Tauri的打包运行依赖特定的系统环境与工具链，所有开发人员必须统一以下基础环境版本：Node.js：推荐使用18.xLTS版本，最低要求16.xLTS。可通过nvm（NodeVersionManager）进行多版本管理，确保团队环境一致性。安装完成后需验证node-v和npm-v命令返回版本符合要求。Rust：必须安装1.70.0及以上稳定版本。通过rustup工具进行安装，执行rustupdefaultstable设置默认稳定版，并使用rustc--version确认版本。系统依赖工具：Windows系统：需安装VisualStudio2022（勾选“桌面开发使用C++”工作负载）、WiXToolset3.14用于生成MSI安装包。macOS系统：需安装Xcode14.0及以上版本，并通过xcode-select--install安装CommandLineTools。Linux系统（以Ubuntu为例）：需安装libwebkit2gtk-4.0-dev、build-essential、curl、wget、libssl-dev、libgtk-3-dev、libayatana-appindicator3-dev等依赖库，执行sudoaptupdate&&sudoaptinstall-y上述依赖包完成安装。1.2项目依赖版本锁定为避免因依赖版本不一致导致的打包问题，所有项目必须在package.json和Cargo.toml文件中锁定依赖版本：前端依赖：在package.json中，将@tauri-apps/cli、@tauri-apps/api等Tauri相关依赖版本号设置为具体数值（如"@tauri-apps/cli":"1.5.0"），而非使用^或~等模糊版本符号。执行npminstall后，需提交package-lock.json文件至代码仓库，确保团队成员安装完全一致的依赖。Rust依赖：在Cargo.toml中，tauri、tauri-build等核心依赖需指定精确版本，如tauri="1.5.0"。执行cargobuild后，提交Cargo.lock文件，保证Rust编译环境的一致性。二、代码质量检查规范2.1前端代码检查在打包前，必须通过以下工具完成前端代码的质量校验：ESLint：配置符合团队规范的ESLint规则，包含变量声明、代码风格、语法错误等检查项。在项目根目录创建.eslintrc.js文件，示例配置如下：module.exports={env:{browser:true,es2021:true,node:true},extends:['eslint:recommended','plugin:@typescript-eslint/recommended'],parser:'@typescript-eslint/parser',parserOptions:{ecmaVersion:'latest',sourceType:'module'},plugins:['@typescript-eslint'],rules:{'no-unused-vars':'warn','@typescript-eslint/no-explicit-any':'error'}}执行npxeslintsrc/**/*.{ts,tsx,js,jsx}命令进行检查，所有错误必须修复后方可进入打包流程。Prettier：统一代码格式化风格，创建.prettierrc文件配置规则：{"semi":true,"singleQuote":true,"printWidth":120,"tabWidth":2}执行npxprettier--writesrc/**/*.{ts,tsx,js,jsx,html,css}命令格式化代码，确保代码风格一致。2.2Rust代码检查Rust代码需通过以下工具保证质量：Clippy：Rust官方代码检查工具，可捕获常见的代码错误、性能问题和不规范写法。在项目根目录执行cargoclippy--all-targets--all-features---Dwarnings，将所有警告视为错误，必须修复所有Clippy提示的问题。rustfmt：用于格式化Rust代码，执行cargofmt--all自动格式化代码，确保代码符合Rust社区规范。提交代码前必须执行此命令，并将格式化后的代码提交至仓库。三、前端资源优化规范3.1静态资源压缩所有前端静态资源（JavaScript、CSS、图片、字体等）必须在打包前进行压缩处理：JS/CSS压缩：使用Vite或Webpack的内置压缩插件，在vite.config.ts中配置如下：import{defineConfig}from'vite';import{tauri}from'@tauri-apps/vite-plugin';exportdefaultdefineConfig({plugins:[tauri()],build:{minify:'terser',terserOptions:{compress:{drop_console:true,drop_debugger:true}}}});上述配置使用Terser压缩JS代码，并移除console和debugger语句，减少包体积。图片压缩：使用sharp或squoosh-cli工具对项目中的PNG、JPG、WebP等图片进行压缩。对于PNG图片，可执行squoosh-cli--oxipnglevel=6src/assets/images/*.png；对于JPG图片，执行squoosh-cli--mozjpegquality=85src/assets/images/*.jpg。压缩后的图片需替换原图片，且保证视觉质量无明显损失。字体优化：仅引入项目中实际使用的字体子集，避免引入完整字体文件。可使用fonttools工具提取所需字符，例如：pyftsubsetsrc/assets/fonts/NotoSansSC.ttf--text="所需字符"--output-file=src/assets/fonts/NotoSansSC-subset.ttf。3.2资源路径处理为避免打包后资源路径错误，必须统一资源引用规范：相对路径使用：在HTML、CSS和JS文件中，所有静态资源引用必须使用相对路径。例如，在Vue组件中引用图片时，使用../assets/images/logo.png而非绝对路径/src/assets/images/logo.png。Vite路径别名配置：在vite.config.ts中配置路径别名，简化资源引用路径，同时避免因目录结构变化导致的路径错误：import{defineConfig}from'vite';importpathfrom'path';exportdefaultdefineConfig({resolve:{alias:{'@':path.resolve(__dirname,'./src')}}});在代码中可通过@/assets/images/logo.png引用资源，提高代码可读性和可维护性。四、Tauri配置文件规范4.1tauri.conf.json核心配置tauri.conf.json是Tauri项目的核心配置文件，必须严格按照以下规范配置：窗口配置：统一窗口的初始大小、最小大小、标题等属性，示例配置如下：{"tauri":{"windows":[{"title":"Tauri应用","width":1200,"height":800,"minWidth":800,"minHeight":600,"resizable":true,"fullscreen":false,"titleBarStyle":"overlay","decorations":true}]}}所有项目的窗口初始大小需根据应用场景合理设置，且必须指定minWidth和minHeight，避免窗口过小导致布局错乱。权限配置：遵循最小权限原则，仅配置应用实际需要的权限。例如，若应用不需要访问文件系统，则不配置fs权限；若仅需要读取文件，配置fs:{"all":false,"read":true}。示例配置：{"tauri":{"allowlist":{"dialog":{"open":true,"save":true},"fs":{"read":true,"write":false},"http":{"all":true,"request":true,"scope":["/*"]}}}}上述配置允许应用使用文件选择对话框、读取文件系统，以及向指定域名发送HTTP请求。打包配置：在tauri.build中配置打包输出目录、安装包名称、图标等信息：{"tauri":{"build":{"distDir":"../dist","devPath":"http://localhost:5173","beforeDevCommand":"npmrundev","beforeBuildCommand":"npmrunbuild","icon":"icons/icon.png"}}}其中，distDir必须指向前端构建后的输出目录，icon需指定一个512x512像素的PNG图标文件，Tauri会自动生成不同平台所需的图标尺寸。4.2Cargo.toml配置优化在Cargo.toml中，需配置以下优化项以减小最终打包体积：编译优化级别：在[profile.release]中设置优化级别为3，并开启lto（链接时优化）：[profile.release]opt-level=3lto=truecodegen-units=1panic='abort'上述配置可显著减小Rust编译后的二进制文件体积，但会增加编译时间。依赖特性裁剪：仅启用Tauri及相关依赖的必要特性。例如，若应用不需要使用Tauri的shell模块，可在Cargo.toml中配置：tauri={version="1.5.0",default-features=false,features=["dialog","fs","http"]}通过default-features=false禁用默认特性，再手动添加所需特性，减少不必要的代码引入。四、多平台打包流程规范4.1Windows平台打包Windows平台支持生成MSI和NSIS两种安装包格式，推荐优先使用MSI格式：前置检查：确保已安装VisualStudio2022和WiXToolset3.14，并将WiXToolset的安装目录（如C:\ProgramFiles(x86)\WiXToolsetv3.14\bin）添加至系统环境变量PATH中。执行打包命令：在项目根目录执行npmruntauribuild----targetx86_64-pc-windows-msvc，Tauri会自动执行前端构建、Rust编译和安装包生成流程。安装包验证：打包完成后，在src-tauri/target/release/bundle/msi目录下找到生成的MSI安装包，双击运行进行安装测试，验证应用是否能正常启动、功能是否完整，以及卸载是否干净。签名配置（可选）：若需要对安装包进行数字签名，需在tauri.conf.json中配置签名信息：{"tauri":{"bundle":{"windows":{"certificateThumbprint":"证书指纹","timestampUrl":""}}}}将上述配置中的证书指纹替换为实际的代码签名证书指纹，打包时Tauri会自动对安装包进行签名。4.2macOS平台打包macOS平台支持生成DMG和App两种格式，其中App格式可直接运行，DMG格式用于分发：前置检查：确保已安装Xcode14.0及以上版本，且已登录Apple开发者账号。在Xcode中配置开发者证书，执行xcode-select-p确认CommandLineTools路径正确。执行打包命令：在项目根目录执行npmruntauribuild----targetaarch64-apple-darwin（针对AppleSilicon芯片）或npmruntauribuild----targetx86_64-apple-darwin（针对Intel芯片）。若需要生成通用二进制包，执行npmruntauribuild----targetuniversal-apple-darwin。代码签名与公证：对于需要分发的应用，必须进行代码签名和公证。在tauri.conf.json中配置签名信息：{"tauri":{"bundle":{"macOS":{"signingIdentity":"DeveloperIDApplication:公司名称(团队ID)","entitlements":"entitlements.plist","hardenedRuntime":true,"gatekeeperAssess":true}}}}上述配置中，signingIdentity需替换为实际的开发者ID证书名称，entitlements.plist为权限配置文件，示例内容如下：<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEplistPUBLIC"-//Apple//DTDPLIST1.0//EN""/DTDs/PropertyList-1.0.dtd"><plistversion="1.0"><dict><key>com.apple.security.cs.allow-jit</key><true/><key>com.apple.security.cs.allow-unsigned-executable-memory</key><true/></dict></plist>打包完成后，Tauri会自动对应用进行签名，并上传至Apple服务器进行公证。公证完成后，应用才能在非开发环境的macOS系统上正常运行。4.3Linux平台打包Linux平台支持生成DEB、RPM和AppImage等格式，推荐使用AppImage格式以实现跨发行版运行：前置检查：确保已安装libwebkit2gtk-4.0-dev等依赖库，且系统为Ubuntu22.04或CentOS8及以上版本。执行打包命令：在项目根目录执行npmruntauribuild----targetx86_64-unknown-linux-gnu生成DEB和RPM包；执行npmruntauribuild----targetx86_64-unknown-linux-musl生成静态链接的AppImage包。AppImage包测试：生成的AppImage包位于src-tauri/target/release/bundle/appimage目录下，执行chmod+x应用名称.AppImage赋予执行权限，然后运行./应用名称.AppImage测试应用是否能正常启动。对于DEB包，可执行sudodpkg-i应用名称.deb进行安装测试；对于RPM包，执行sudorpm-i应用名称.rpm进行安装测试。五、打包后测试规范5.1功能完整性测试打包完成后，必须对应用的核心功能进行全面测试，包括但不限于：界面交互测试：测试所有按钮、输入框、下拉菜单等UI元素的交互是否正常，点击、输入、选择等操作是否能触发预期的响应。业务逻辑测试：测试应用的核心业务流程，如数据查询、文件上传下载、用户登录注册等功能是否正常运行，数据处理结果是否正确。系统集成测试：测试应用与系统资源的交互是否正常，如访问文件系统、调用系统对话框、与其他应用程序的交互等。例如，测试文件选择对话框是否能正常打开，选择的文件是否能被正确读取。5.2性能测试对打包后的应用进行性能测试，确保运行流畅：启动时间测试：记录应用从双击图标到完全加载完成的时间，Windows平台要求启动时间不超过3秒，macOS和Linux平台要求不超过2秒。可使用time命令在Linux和macOS平台测试启动时间，如time./应用名称.AppImage。内存占用测试：使用系统自带的任务管理器（Windows）、活动监视器（macOS）或top命令（Linux）监测应用运行时的内存占用情况。对于常规前端应用，内存占用应控制在500MB以内；对于复杂应用，内存占用应控制在1GB以内。CPU占用测试：在应用运行核心功能时，监测CPU占用率，确保峰值CPU占用率不超过80%，且在空闲状态下CPU占用率不超过5%。5.3兼容性测试在不同版本的操作系统上测试应用的兼容性：Windows系统：在Windows1022H2和Windows1122H2版本上进行测试，确保应用能正常安装、启动和运行，且界面显示正常。macOS系统：在macOS13（Ventura）和macOS14（Sonoma）版本上进行测试，验证应用的兼容性，特别是针对AppleSilicon和Intel芯片的适配情况。Linux系统：在Ubuntu22.04、Fedora38和ArchLinux等主流发行版上进行测试，确保AppImage包能在不同发行版上正常运行。六、打包产物管理规范6.1产物存储与命名打包生成的所有产物必须按照以下规范存储和命名：存储路径：在项目根目录创建dist-packages目录，按照平台和版本号进行分类存储，例如：dist-packages/├──windows/│├──v1.0.0/││├──应用名称_1.0.0_x64_en-US.msi││└──应用名称_1.0.0_x64_en-US.exe├──macos/│├──v1.0.0/││├──应用名称_1.0.0_x64.dmg││└──应用名称_1.0.0_universal.dmg└──linux/├──v1.0.0/│├──应用名称_1.0.0_x64.AppImage│├──应用名称_1.0.0_amd64.deb│└──应用名称_1.0.0_x86_64.rpm命名规则：安装包名称格式为应用名称_版本号_架构_语言.扩展名，其中版本号遵循SemVer规范（如1.0.0表示主版本号.次版本号.修订号），架构包括x64、aarch64、universal等，语言代码遵循ISO639-1标准（如en-US表示美式英语）。6.2版本号管理所有版本号必须遵循SemVer2.0.0规范：主版本号（MAJOR）：当应用进行不兼容的API更改时，主版本号递增，例如从1.0.0升级到2.0.0。次版本号（MINOR）：当应用添加了向后兼容的新功能时，次版本号递增，例如从1.0.0升级到1.1.0。修订号（PATCH）：当应用进行了向后兼容的问题修复时，修订号递增，例如从1.0.0升级到1.0.1。在打包前，必须更新package.json中的version字段和src-tauri/Cargo.toml中的version字段，确保两者版本号一致。6.3产物分发规范打包产物的分发必须遵循以下规范：内部测试分发：对于内部测试版本，可通过企业内部文件服务器或即时通讯工具进行分发，并明确标注“测试版本”字样，提醒测试人员注意数据安全。正式版本分发：正式版本需上传至官方下载网站、应用商店（如MicrosoftStore、MacAppStore）或开源软件平台（如GitHubReleases）。在GitHubReleases中，需提供完整的版本更新日志，包括新增功能、修复的问题、兼容性信息等内容。同时，需为每个安装包生成SHA256校验值，供用户验证文件完整性，例如：应用名称_1.0.0_x64_en-US.msi:SHA256=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890用户可通过certutil-hashfile应用名称.msiSHA256（Windows）或shasum-a256应用名称.msi（macOS/Linux）命令验证文件的SHA256值是否与提供的一致。七、异常处理与日志规范7.1打包异常处理在打包过程中，若遇到错误，必须按照以下步骤进行处理：查看错误日志：Tauri的打包日志会输出至控制台，同时会在src-tauri/target/debug或src-tauri/target/release目录下生成build.log文件。首先查看日志中的错误信息，定位问题根源。常见问题排查：依赖安装失败：若提示Rust依赖安装失败，可执行cargoclean清除本地依赖缓存，然后重新执行cargobuild。若前端依赖安装失败，执行rm-rfnode_modulespackage-lock.json（Windows为rmdir/s/qnode_modules&&delpackage-lock.json），然后重新执行npminstall。编译错误：若Rust编译失败，需根据错误提示检查代码中的语法错误、类型不匹配等问题。若为Windows平台编译错误，需检查VisualStudio是否正确安装，以及环境变量是否配置正确。打包失败：若提示安装包生成失败，需检查tauri.conf.json中的配置是否正确，如distDir是否指向正确的前端构建目录，icon文件是否存在且格式正确。问题记录与反馈：对于无法解决的问题，需详细记录错误信息、环境配置、操作步骤等内容，提交至Tauri官方GitHub仓库的Issues页面，或在TauriDiscord社区寻求帮助。7.2应用运行日志规范为便于排查应用运行时的问题，必须在应用中实现日志记录功能：前端日志：使用console.log、console.error等方法记录前端日志，并通过Tauri的fs模块将日志写入系统日志目录。例如，在Vue组件中：import{writeTextFile,BaseDirectory}from'@tauri-apps/api/fs';constlogMessage=(message:string,level:'info'|'error'='info')=>{constlogContent=`[${newDate().toISOString()}][${level}]${message}\n`;writeTextFile('app.log',logContent,{dir:BaseDirectory.Log,append:true}).catch(err=>console.error('写入日志失败:',err));};上述代码将日志写入系统的日志目录（Windows为C:\Users\用户名\AppData\Roaming\应用名称\logs，macOS为~/Library/Logs/应用名称，Linux为~/.config/应用名称/logs）。Rust日志：使用tracing或logcrate记录Rust后端日志，并配置日志输出级别。在src-tauri/src/main.rs中配置：usetracing_subscriber::{fmt,layer::SubscriberExt,util::SubscriberInitExt};fnmain(){tracing_subscriber::registry().with(fmt::layer().with_target(false)).with(tracing_subscriber::EnvFilter::new(std::env::var("RUST_LOG").unwrap_or_else(|_|"tauri=info,应用名称=debug".into()),)).init();tauri::Builder::default().run(tauri::generate_context!()).expect("运行应用失败");}上述配置将Rust日志输出至控制台，同时可通过设置RUST_LOG环境变量调整日志级别。在打包后的应用中，可通过命令行参数指定日志输出文件，例如：应用名称.exe--log-file=app.log。八、持续集成与自动化打包规范8.1CI/CD流程配置为提高打包效率和一致性，必须配置持续集成与自动化打包流程，推荐使用GitHubActions或GitLabCI：GitHubActions配置示例：在项目根目录创建.github/workflows/tauri-build.yml文件，内容如下：name:TauriBuildon:push:tags:-'v*'pull_request:branches:-mainjobs:build-windows:runs-on:windows-2022steps:-uses:actions/checkout@v4-name:设置Node.js环境uses:actions/setup-node@v4with:node-version:'18'-name:安装Rust环境uses:dtolnay/rust-toolchain@stablewith:toolchain:stable-name:安装系统依赖run:|chocoinstallwixtoolset--version3.14.0-name:安装前端依赖run:npminstall-name:打包应用run:npmruntauribuild-name:上传产物uses:actions/upload-artifact@v4with:name:windows-packagespath:src-tauri/target/release/bundle/msi/*.msibuild-macos:runs-on:macos-13steps:-uses:actions/checkout@v4-name:设置Node.js环境uses:actions/setup-node@v4with:node-version:'18'-name:安装Rust环境uses:dtolnay/rust-toolchain@stablewith:toolchain:stable-name:安装前端依赖run:npminstall-name:打包应用run:npmruntauribuild-name:上传产物uses:actions/upload-artifact@v4with:name:macos-packagespath:src-tauri/target/release/bundle/dmg/*.dmgbuild-linux:runs-on:ubuntu-22.04steps:-uses:actions/checkout@v4-name:设置Node.js环境uses:actions/setup-node@v4with:node-version:'18'-name:安装Rust环境uses: