Quasar CLIquasar/app-viteElectron 应用开发与构建命令完全指南【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar本指南围绕 Quasar 官方 CLI 包quasar/app-vite的 Electron 模式系统讲解从quasar dev -m electron开发调试、quasar build -m electron生产打包到electron-builder发布上线的完整命令链路与输出产物结构。读完本文你将掌握 Electron 模式下开发命令的参数语义、调试工具Chrome/Vue DevTools的启用方式、electron/packager与electron-builder两种打包器的选择与发布配置并能结合仓库源码理解主进程、preload 脚本与渲染进程的编译分工。Electron 模式概览一条命令启用桌面应用能力在quasar/app-vite中Electron 模式与 SPA、SSR、PWA 等模式平级通过quasar dev与quasar build的--mode electron或-m electron选项启用。与 Cordova/Capacitor 类似首次执行时 CLI 会自动安装 Electron 模式在项目根目录创建/src-electron目录并根据项目是否使用 TypeScript 拷贝js或ts模板见 electron-installation.js其中包含electron-main.js/ts、electron-preload.js/ts、electron-assets应用图标与独立的package.json。Electron 模式将应用划分为三个构建单元见 electron-config.js渲染进程UI即/src下的 Vite 应用负责界面渲染开发时支持 HMR主进程Main/src-electron/electron-main.js/ts使用 Rolldown 编译为 ESM负责创建窗口、系统集成等Preload 脚本默认/src-electron/electron-preload.js/ts使用 Rolldown 编译为CommonJS.cjs因为 Electron 的沙箱化 preload 只支持 CJS不支持 ESM 上下文见 electron-config.js。开发模式quasar dev -m electron启动 Electron 开发模式的完整命令形态如下quasar dev -m electron # 或完整写法 quasar dev --mode electron # 向底层 electron 可执行文件透传额外参数/选项 quasar dev -m electron -- --force-device-scale-factor1 # Windows 下使用 Powershell 时 quasar dev -m electron -- --force-device-scale-factor1命令执行后会自动打开一个 Electron 窗口默认模板还会打开渲染进程的 DevTools。开发体验的关键特性渲染进程支持 HMR修改/src下的 UI 代码会热更新主进程 / preload 改动自动重启修改electron-main或electron-preload源码后CLI 会重新编译并重启 Electron 进程而不是整体重启开发服务器。这一行为由 electron-devserver.js 中的watchWithRolldown机制实现isReady标志为真时任何构建回调都会触发#runElectron()而#runElectron()会先process.kill旧进程、等待约 100ms 释放资源后再启动新进程见 electron-devserver.js。向 Electron 透传参数-- 之后的参数--之后的所有参数会原样追加到 Electron 可执行文件的调用参数中最终由 electron-devserver.js 中的spawn(electronExecutable, [--inspect端口, electronEntryDir, ...this.argv._])生效。文档示例中的--force-device-scale-factor1是沙箱禁用类参数仅应在受限环境下确有需要时使用并务必先评估其安全影响。此外开发模式下 CLI 总会以--inspectport启动 Electron端口可通过quasar.config electron inspectPort配置默认5858见 configuring-electron.md。Chrome DevTools开发模式下当应用窗口获得焦点时按以下组合键即可打开 Chrome DevToolsmacOSCmdAltI或F12LinuxCtrlShiftI或F12WindowsCtrlShiftI或F12在默认模板的 electron-main.js 中可以看到 DevTools 的完整控制逻辑QUASAR_DEBUG为真时调用webContents.openDevTools()生产模式下则监听devtools-opened事件并强制关闭禁止用户在打包后的应用里打开开发者工具。Vue DevToolsElectron 的渲染进程即 Vue 应用可通过以下命令加载 Vue DevToolsquasar dev -m electron --devtools--devtools短写-d在 dev.js 中被声明并被映射为vueDevtools: argv.devtools传入配置上下文CLI 会按需自动安装vite-plugin-vue-devtools依赖见 app-devserver.js。注意这里的-d与构建命令中的--debug含义不同一个用于开发期调试工具一个用于生产调试构建。生产构建quasar build -m electron构建 Electron 生产版本的命令quasar build -m electron # 或完整写法 quasar build --mode electron该命令会依次完成编译 UIVite→ 编译主进程RolldownESM→ 编译全部 preload 脚本RolldownCJS→ 生成生产package.json→ 拷贝electron-assets等文件 → 在UnPackaged目录安装生产依赖 → 调用所选打包器产出最终应用。上述并行构建流程见 electron-builder.js 的build()方法。如果需要对 UI 代码启用调试支持的生产构建quasar build -m electron -d # 或完整写法 quasar build -m electron --debug--debug-d在 build.js 中声明它会让编译后的package.json以格式化缩进方式输出并在运行时保留 DevTools 访问能力。构建输出目录结构构建产物位于dist/electron即dist-electron结构如下dist-electron/ ├── Packaged/ # 由 electron/packager 或 electron-builder 打包出的应用 └── UnPackaged/ # 未打包的中间产物 ├── assets/... # Vite 编译后的 /src 资源 ├── electron-assets/ # /src-electron/electron-assets 原样拷贝 │ └── icons/ # Electron 应用图标 ├── node_modules/ # 生产依赖 ├── index.html ├── package.json # 生产清单main 指向 ./electron-main.js ├── electron-main.js # 编译后的主进程入口 ├── electron-preload.cjs # preload 脚本Electron 仅支持 CJS └── ... # /public 目录内容其中UnPackaged目录在打包前还包含一个关键步骤若检测到pnpm-workspace.yamlCLI 会自动追加shamefullyHoist: true确保打包器能在node_modules中找到依赖否则会出现 Cannot find module 错误见 electron-builder.js。常用构建参数速查Electron 模式专用的构建参数见 build.js 的帮助文本参数说明--bundler, -b选择打包器packager默认electron/packager或builderelectron-builder--arch, -A目标架构。packageria32\|x64\|armv7l\|arm64\|mips64el\|allbuilderia32\|x64\|armv7l\|arm64\|all。默认跟随当前主机--target, -T目标平台。packagerdarwin\|win32\|linux\|mas\|allbuilderdarwin\|mac\|win32\|win\|linux\|all。默认跟随当前主机--skip-pkg, -s只构建 UI仅生成UnPackaged目录跳过打包--debug, -d生产调试构建--publish, -P触发发布仅 electron-builder 有效跳过打包与 beforePackaging 钩子--skip-pkg在 electron-builder.js 中生效为真时直接跳过#packageFiles()。若需要打包#packageFiles()见 electron-builder.js会依次在UnPackaged目录以production环境安装依赖参数可经quasar.config electron unPackagedInstallParams定制如[install, --production, --ignore-optional, --some-other-param]若配置了electron.beforePackaging执行该钩子可拿到appPaths与unpackagedDir适合注入签名、资源等操作根据bundler选择打包器执行packager 会自动从/src-electron/package.json读取并注入electronVersionbuilder 则调用其build()方法。打包器选型electron/packager vs electron-builderquasar build -m electron默认使用electron/packager它只产出应用目录/可执行文件当需要安装包installer、代码签名、自动发布等能力时应切换为electron-builder。切换方式二选一# 命令行指定 quasar build -m electron --bundler builder// 或在 quasar.config 中固化配置 electron: { bundler: builder // 优先级同命令行 --bundler }两者的配置对象分别放在electron.packager与electron.builder下。注意packager 配置中dir与out两个字段由 Quasar 控制不应自行设置见 configuring-electron.md。打包器相关配置项来自 configuring-electron.mdpreloadScripts?: string[]需要编译的 preload 脚本清单值为/src-electron/下的文件名不含扩展名默认[electron-preload]extendElectronPackageJson?: (pkgJson) void | object | Promise...增删改生产package.json的属性可异步、可原地修改beforePackaging?: (context) void | Promisevoid生产依赖安装完成后、打包器运行前执行extendElectronMainConf/extendElectronPreloadConf扩展主进程 / preload 的 Rolldown 配置可异步bundler?: packager | builder打包器选择unPackagedInstallParams?: string[]UnPackaged目录安装依赖时的额外参数inspectPort?: number开发模式调试端口默认 5858。跨平台打包的现实约束打包、签名与原生依赖受宿主平台限制例如签名 macOS 应用必须在 macOS 上进行从其他平台打包 Windows 资源可能需要 Wine。涉及签名或原生模块时务必查阅所选打包器packager/builder的平台要求在匹配的宿主系统或 CI Runner 上构建对应目标。发布quasar build -m electron -P仅 electron-builder当使用electron-builder作为打包器时--publish/-P参数具有特殊含义——触发发布钩子quasar build -m electron -P always # 或完整写法 quasar build --mode electron --publish always-P的合法取值见 build.jsonTag、onTagOrDraft、always、never。发布仅对electron-builder生效因此必须通过--bundler builder或quasar.config electron.bundler选定 builder并在quasar.config electron builder publish配置受支持的 provider如 GitHub Releases、S3、Generic 等。一个将 Windows EXE 安装包发布到 Amazon S3 的最小配置示例// quasar.config 文件 electron: { bundler: builder, // 在此处配置也可用命令行 --bundler builder builder: { appId: com.electron.myelectronapp, win: { target: nsis }, publish: { provider: s3, bucket: myS3bucket } } }当-P被传入时构建流程在打包完成后还会触发quasar.config.build.onPublish回调以及应用扩展的onPublish钩子见 build.js可用于扩展发布行为。深入生产 package.json 是如何生成的UnPackaged/package.json是打包应用运行时的元数据来源其生成逻辑见 electron-builder.js值得理解以根目录package.jsonappPkg为基础合并dependencies被替换为/src-electron/package.jsonelectronPkg中的依赖经getPinnedDeps固定版本并删除devDependencies、scripts、quasarCli字段——目的是加快安装速度、缩小包体main被固定为./electron-main.js若配置了extendElectronPackageJson函数则执行并深度合并其返回值随后应用扩展的extendElectronPackageJson钩子也会被依次执行。同时#copyElectronFiles()见 electron-builder.js会把.npmrc、.yarnrc、package-lock.json、yarn.lock、src-electron/electron-assets与src-electron/pnpm-workspace.yaml拷贝进UnPackagedpnpm-lock.yaml与bun.lockb会被有意忽略避免 lockfile is frozen 错误。依赖拆分的最佳实践生产环境只安装/src-electron/package.json中的dependencies安装发生在打包前见 electron-builder.js。因此仅渲染进程使用的依赖保留在根package.json它们已被 Vite/Rolldown 打进 bundle无需出现在生产依赖中Electron 运行时依赖放入/src-electron/package.json的dependenciespreload 的 import 会被打包进产物但沙箱化的 preload 无法使用任意 Node.js API 或原生模块——需要特权能力时应把重活放到主进程并通过 IPC 暴露窄接口默认模板的 electron-preload.js 只通过contextBridge.exposeInMainWorld暴露quasarRuntime正是这一原则的体现谨慎使用extendElectronPackageJson若移除了被外部化external主进程代码所依赖的包会导致打包后的应用运行时崩溃。延伸阅读Configuring ElectronElectron 模式完整配置参考quasar.config中electron块的全部配置项与 TS 类型说明主进程与 preload 的编译细节electron-config.js其中主进程在开发模式使用虚拟入口rolldown.virtual-entry.js以正确处理相对导入并在 macOS 开发期通过NativeImageAPI 为 Dock 设置 PNG 图标构建与打包实现electron-builder.js、electron-devserver.js默认主进程模板electron-main.js其中QUASAR_DEV、QUASAR_APP_URL、QUASAR_DEBUG等由 CLI 注入的环境变量区分了开发加载 URL、生产加载文件与调试模式。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考