Quasar Electron 应用依赖管理指南正确区分主进程依赖与渲染进程依赖【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar导读在 Quasar 项目quasar/app-vite中添加 Electron 模式后会出现两个package.json一个在项目根目录另一个在/src-electron目录。本篇指南以 Quasar 官方文档为准绳结合本仓库源码app-vite/lib/modes/深入讲解哪些依赖必须放进/src-electron/package.json哪些必须留在根目录package.json以及 Electron、打包工具和主进程运行时依赖各自的正确安装位置与方法。读完本文你将能准确区分主进程依赖与渲染进程依赖彻底避免 Electron 专用包被错误打进渲染层 bundle 的问题。为什么要单独维护/src-electron/package.jsonQuasar 的 Electron 模式将项目拆分为两个完全独立的环境渲染进程Renderer即/src下的 Vue 应用代码由 Vite 负责打包产物是纯 Web 资源主进程Main Process与打包流程即/src-electron下的 Electron 代码由 Rolldown 编译并最终通过打包工具electron/packager或electron-builder产出桌面应用安装包。官方文档明确指出Use/src-electron/package.jsonfor dependencies that belong to the Electron main process or its packaging workflow. Keeping them in this workspace prevents Electron-only packages from becoming renderer dependencies.把 Electron 相关依赖隔离在/src-electron这个独立 workspace 中的核心收益是防止 Electron 专用包如electron本身、electron-store、node-pty等被 Vite 误解析进渲染进程的 bundle。渲染进程代码经 Vite 打包后运行在 Chromium 沙箱中本就不应包含 Node.js 原生模块或 Electron API 相关依赖。从仓库源码可以印证这一隔离机制。electron-installation.js中的addMode会从模板复制/src-electron工作区electron-installation.js并在安装完成后把当前环境已安装的 Electron 版本以^前缀写回/src-electron/package.json的devDependencies中electron-installation.js。这说明/src-electron是一个独立安装依赖的 workspace有自己专属的node_modules和锁文件。/src-electron/package.json的标准结构与初始内容当执行quasar mode add electron之后Quasar 会在项目根目录创建/src-electron目录并生成一份标准的package.json。其内容如下对应仓库模板 app-vite/templates/electron/common/package.json{ name: quasar-electron-app, version: 1.0.0, description: Quasar Electron Folder, private: true, type: module, devDependencies: { electron: ^installed-version } }几个关键字段说明private: true防止该包被意外发布到 npm 仓库type: module声明该 workspace 下的源码使用 ESM 语法。这也与主进程编译行为一致——electron-config.js中主进程main以format: esm编译electron-config.js而 preload 脚本出于 Electron 安全约束沙箱化 preload 脚本不支持 ESM 上下文被强制编译为 CommonJSelectron-config.jsdevDependencies.electronElectron 本体属于构建期工具放在devDependencies中。注意模板中的初始版本写作electron: latest但在quasar mode add electron执行时addMode会读取当前环境实际安装的 Electron 版本并将其写回为^installed-version确保版本与实际环境一致。依赖分类运行时依赖 vs 构建期依赖官方文档给出了明确的划分原则From/src-electron, install packages used at runtime by the main process underdependencies. Install Electron, packaging tools, type packages, and other build-time tools underdevDependencies.即类别安装位置典型示例说明主进程运行时依赖/src-electron/package.json的dependencieselectron-store、node-pty、sqlite3等主进程import/require的库会被安装进最终打包产物随应用一起分发构建期工具/src-electron/package.json的devDependencieselectron、electron/packager、electron-builder、types/electron等只在开发与打包阶段使用不会进入最终产物渲染进程依赖根目录package.jsonVue、Quasar 组件、axios 等/src代码 import 的库由 Vite 打包进渲染层 bundle从源码角度看这种区分是硬性的。electron-config.js中主进程的 Rolldown 编译配置将electron以及quasarConf.ctx.pkg.electronPkg.dependencies中的全部键声明为externalelectron-config.js也就是说只有写在/src-electron/package.json的dependencies中的包才会在主进程编译时被当作外部依赖保留运行时通过 Node.js 从/src-electron/node_modules解析加载而devDependencies里的内容根本不会参与主进程产物的依赖解析。同时preload 脚本与主进程的模块解析路径被显式指向/src-electron/node_moduleselectron-config.js再次印证主进程相关代码只认/src-electron这个 workspace 内的依赖。四种包管理器下的安装命令官方文档为当前主流的四种包管理器分别给出了标准安装命令PNPM、Yarn、NPM、Bun并且必须在/src-electron目录下执行即cd src-electron之后# ---------- PNPM ---------- # Runtime dependency installed into the packaged app: pnpm add deps # Build-time dependency: pnpm add -D dev-deps # ---------- Yarn ---------- # Runtime dependency installed into the packaged app: yarn add deps # Build-time dependency: yarn add -D dev-deps # ---------- NPM ---------- # Runtime dependency installed into the packaged app: npm install deps # Build-time dependency: npm install -D dev-deps # ---------- Bun ---------- # Runtime dependency installed into the packaged app: bun add deps # Build-time dependency: bun add -D dev-deps不带-D的包会写入dependencies随打包产物分发到用户机器带-D的包写入devDependencies仅存在于开发环境。为什么必须在/src-electron目录内执行安装因为/src-electron被设计为独立的包管理器 workspace。仓库源码中的ensureModeDeps会在 Electron 模式首次启用时以/src-electron为工作目录调用当前包管理器执行安装modes-utils.js。而copyModeWorkspace在检测到使用 pnpm 时还会额外把templates/workspace含pnpm-workspace.yaml复制进/src-electronmodes-utils.js。/src-electron/pnpm-workspace.yaml的作用有两层见模板 app-vite/templates/electron/common/pnpm-workspace.yaml强制 pnpm 在此目录安装依赖不受上层 workspace 影响pnpm install会在此执行通过onlyBuiltDependencies: [electron]显式放行 electron 的 postinstall 脚本——因为 pnpm 默认禁止依赖执行生命周期脚本而 electron 的 postinstall 正是负责下载 Electron 二进制文件的步骤。打包工具依赖何时被安装官方文档强调Quasar installs the selected packaging tool (electron/packagerorelectron-builder) here on the first production build that needs it.也就是说你不需要手动安装打包工具。在首次执行生产构建如quasar build -m electron且构建流程确实需要打包时Quasar 会自动把所选打包工具安装到/src-electron。这一行为在electron-builder.js的#packageFiles()中有完整的调用链支撑electron-builder.js构建流程先通过nodePackager.install()在dist/electron/UnPackaged目录执行production环境的依赖安装electron-builder.js该步骤只安装dependencies而不安装devDependencies随后根据quasarConf.electron.bundler配置packager或builder调用getBundler()获取对应的打包工具并分别以electron/packager或electron-builder的 API 执行打包electron-builder.js。由于打包工具属于构建期工具即使被 Quasar 自动安装也只会进入/src-electron的devDependencies范畴不会进入最终分发产物。打包阶段对依赖的版本固定处理值得一提的是#writePackageJson()会读取/src-electron/package.json的dependencies通过getPinnedDeps()将其中的 semver 范围转换为精确版本号再写入dist/electron/UnPackaged/package.jsonelectron-builder.js。getPinnedDeps的实现会解析已安装包的package.json把^2.0.0之类的范围固化为实际安装版本如2.7.1URL 形式的依赖则原样保留get-pinned-deps.js。这保证了打包产物内依赖版本与开发环境完全一致可复现、可追溯。同时生成的UnPackaged/package.json会删除devDependencies、scripts、quasarCli等字段并把main指向./electron-main.jselectron-builder.js——这就是为什么运行时依赖必须放在dependencies只有dependencies会进入 UnPackaged 目录的安装与最终产物。渲染进程依赖留在根目录package.json官方文档最后明确指出Renderer dependencies imported by code under/srcbelong in the rootpackage.jsonand are bundled by Vite.凡是被/src下代码import的库Vue 生态、Quasar 组件、axios、pinia 等都必须安装在根目录的package.json中。这些依赖由 Vite 直接打包进渲染进程的 bundle不经过 Electron 的运行时模块解析因此与/src-electron的 workspace 无关。这一点在构建配置中同样有据可查渲染进程使用 Vite 构建cfg.optimizeDeps.exclude [electron]electron-config.js——electron包被显式排除在 Vite 的依赖预构建之外且渲染层代码根本不应该出现对electron的 import。若误将渲染进程依赖装进/src-electron/package.jsonVite 将无法从根目录的node_modules找到它们导致打包失败或运行时模块缺失。快速自查清单在开发过程中可用以下清单快速判断某个依赖应该装到哪里这个包是否只被/src-electron主进程、preload或打包流程使用→ 装到/src-electron/package.json它是主进程运行时要import的库还是只是构建/打包/类型工具→ 运行库放dependencies工具放devDependencies这个包是否被/src下的渲染进程代码引用→ 放根目录package.json打包工具electron/packager/electron-builder是否需要手动安装→ 不需要Quasar 会在首次生产构建时自动安装到/src-electron是否使用 pnpm→ 确保/src-electron/pnpm-workspace.yaml存在且包含onlyBuiltDependencies: [electron]否则 Electron 二进制可能下载失败。遵循以上规则你就能让 Electron 专属依赖与渲染进程依赖各归其位构建产物更小、安装流程更可靠、打包产物可复现也从根源上杜绝了Electron 专用包混入渲染层这一经典配置错误。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考