现代桌面项目目录为何和Web工程一样？进程模型与目录结构全解析

前一阵有个做服务端开发的朋友问了我一个挺有意思的问题：他从 GitHub 拉了一个基于 Electron 的桌面工具源码，想改点行为，结果打开项目一看，里面全是 src/main、src/renderer、dist、public、package.json 之类的文件，跟他平时开发的 Web 项目不能说很像，只能说一模一样。他就很困惑：做桌面应用，目录怎么长得和 Web 项目一个样？

这事解释起来并不复杂，但背后牵扯到桌面开发十几年来的习惯变化。如果你以前写过 MFC、Qt、WinForms 这类传统桌面程序，刚接触现在的跨平台桌面框架时，多半也会有这种“走错片场”的感觉。反过来，如果你本来做 Web 前端，第一次打开现代桌面项目反倒会觉得亲切。这篇文章想把这种“错位”讲清楚：现代应用为什么要长成这种目录结构，以及当你自己准备新建或改造一个桌面项目时，这套结构到底要怎么拆。

1. 从“一个进程干到底”到“按进程分目录”：桌面项目组织方式变了

1.1 先给结论：目录结构本质是运行模型的投影

很多人第一次看到现代桌面项目的目录，会下意识以为这是“前端工程化”塞进了桌面开发。这个判断方向是对的，但不够准确。

更准确的说法是：目录结构是运行时模型的投影。项目里有哪些独立的运行单元，源码目录就会跟着拆出对应的顶层文件夹。

Electron 这类框架跑起来有两个完全独立的运行时：主进程和渲染进程。主进程就是那个掌管窗口、菜单、系统通知、文件读写的宿主进程；渲染进程则是承载页面的浏览器内核实例。因为两个进程的生命周期、权限、可调用的 API 完全不同，所以源码必须从一开始就分开管理。于是就有了 src/main 和 src/renderer 这种在传统桌面项目里几乎见不到的顶层目录。

传统桌面框架则不太一样。Qt 程序写完后就是一个进程，内部虽然有主线程、工作线程，但共享同一份内存、同一套 C++/QML 运行时。因为它不存在进程级隔离，目录结构自然也不会按“进程”来拆，而是按“模块”或“层次”拆：UI 层归 UI 层，业务层归业务层，数据层归数据层。

所以你会发现一个有意思的现象：老派桌面项目目录里经常出现的是 ui/、controller/、service/、model/ 这类“逻辑分层”，而新派桌面项目目录里常见的是 main/、renderer/、preload/ 这类“运行时分区”。差别背后不是谁比谁高级，而是底层运行模型变了。

1.2 我用 Qt 顺手写画线工具时是怎么组织代码的

拿我自己早年的经历类比一下。那时候我经常拿 Qt 写一些小工具，比如一个能加载图纸、支持鼠标拖动画线的桌面端小程序。

最开始的版本非常简单，十几个类全塞在一个平铺目录里，找起来靠 IDE 的文件树。后来功能多了，就自然拆成了这样：

code复制paint-tool/
├── ui/
│   ├── mainwindow.ui
│   └── drawcanvas.ui
├── controller/
│   └── drawcontroller.cpp
├── service/
│   ├── shapefactory.cpp
│   └── renderengine.cpp
├── model/
│   ├── shape.h
│   └── document.h
└── resources/
    └── app.rc

这套结构在 Qt 项目里很典型：按职责切分，同一个模块的数据、界面、控制代码各归各位。它运行在同一个进程里，目录分层更多是给“人”看的，帮助开发者快速定位一段逻辑在哪个层。进程内并没有真正隔离访问权限，UI 层想要直接 new 一个 Model 对象，技术上完全可行，规范层面才会约束你不要这么干。

现代桌面框架走的是另一条路：主进程目录里的代码，根本不会和渲染进程共享同一个 JS 上下文。你在 main/ 里写错了代码，崩溃的只是宿主进程；你在 renderer/ 里写错了代码，白屏的只是页面区域。这种物理边界直接反映到目录上，所以目录结构天然比传统 Qt 项目更强调“分区”而不是“分层”。

1.3 为什么说“跨平台”是目录结构变化的导火索

还有一个角度很容易被忽略：真正的导火索是跨平台。

以前写 Windows 桌面软件，需求就是跑在 Windows 上，你只需要编译出一个 exe，跟系统 API、注册表、服务打交道都是单平台的。Qt 虽然跨平台，但项目里仍然要维护大量 #ifdef 和不同平台的资源文件，打包脚本也各异。相比之下，Electron、Tauri 这类方案把“跨平台能力”收敛到框架层，应用本身用 HTML/CSS/JS 或 Rust + WebView 书写，源码层面几乎不需要按平台拆目录。

平台差异被抹平之后，剩下的核心差异就只剩进程了。目录结构自然就跟着进程模型走，而不是平台走。理解了这一层，后面再看到 src/main、src/renderer 就不会觉得奇怪了。

2. 主进程、预加载脚本和渲染进程：目录里三条主线的分工逻辑

2.1 src/main 的职责不是写 UI，而是管“窗”和“命”

现代桌面项目的 src/main 目录，很多人都以为它是“主入口”，只是放一个 index.js 把窗口创建出来。实际项目里远远不止这么简单。

主进程承担的是所有需要操作系统能力的逻辑，包括窗口生命周期、系统托盘、全局快捷键、菜单、文件对话框、自动更新、原生模块调用、数据库本地落盘等。它本质上像是“桌面端的后端”，只不过这个后端不是跑在远程服务器上，而是跑在用户电脑的本地宿主里。

所以你看成熟的开源项目，src/main 里边一般还会有更细的子目录：

code复制src/main/
├── index.ts
├── windows/
│   └── mainWindow.ts
├── ipc/
│   └── handlers/
├── services/
│   ├── updater.ts
│   └── storage.ts
└── utils/

windows/ 管窗口配置，ipc/handlers/ 管主进程对外暴露的接口，services/ 管具体业务，比如自动更新、本地数据库、文件扫描。这样拆的原因是主进程的逻辑也可以很复杂，如果不按职责继续分层，几百行全堆在 index.ts 里，后面加一个功能就要翻半天代码。

我个人的习惯是，入口文件只做三件事：注册窗口创建方法、注册 IPC 监听、初始化需要的服务。其余逻辑一律下沉到子模块。入口文件越“薄”，后面排查启动问题越省事。

2.2 src/preload 为什么会单独占一层目录

preload 是很多刚从 Web 转过来的开发者最陌生的目录。它既不写界面，也不做业务，看起来像个夹层，但它恰恰是安全边界最重要的落点。

多数现代桌面框架默认开启 contextIsolation，意思是渲染进程里不能直接 require Node.js 模块，也不能访问主进程的任意对象。再加上 CSP 限制，页面里跑的任何脚本都先被当成“不可信”代码。那页面确实需要读取本地文件、调用系统能力怎么办？就是通过 preload 脚本暴露一个白名单 API。

preload 脚本运行在一个特殊的上下文里，它既不是主进程也不是渲染进程，能访问部分 Node.js 能力，但同时可以用 contextBridge 把方法暴露给 window。简单说，它是中间的“合法渡口”。

目录安排上，preload 通常只拆成两个文件：

• preload/index.ts：负责暴露 API 对象。
• preload/index.d.ts：给渲染进程提供 TypeScript 类型提示。

这里我不推荐做得太复杂。preload 越薄越好，尽量只做参数透传和 IPC invoke，真正的业务要放在主进程里。见过一些项目把文件读写的逻辑直接写在 preload 里，等于在沙箱边界上开了个大口子，安全性和可维护性都很成问题。

2.3 src/renderer：它就是一个完整独立的 Web 应用

渲染进程的代码，本质上就是你在浏览器里跑的那个页面。过去你写 Vue、React、构建工具链、状态管理、路由、组件库，在这里全部照常生效。

这块目录结构对前端开发来说没有任何学习成本：

code复制src/renderer/
├── index.html
├── src/
│   ├── assets/
│   ├── components/
│   ├── pages/
│   ├── router/
│   ├── stores/
│   └── api/
└── public/

很多会问，既然它就是一个 Web 应用，为什么不直接塞一个 Web 项目进去，非要单独弄个 renderer/ 目录包一层？原因是我前面说的，Electron 的构建工具要同时处理主进程、preload、渲染进程三种入口。如果三者不分开，electron-vite 没法精准判断哪个文件该用 Node 环境编译、哪个文件该用浏览器环境编译。打包时产生的 sourcemap 和产物目录也容易互相污染。

把渲染进程独立成目录，等于在构建工具层面明确了边界：这个子树下的资源统统按 Web 方式处理，输出到 out/renderer；那个子树下的资源按 Node 方式处理，输出到 out/main。没有物理分隔，配置根本无从谈起。

这也能解释为什么这类项目根目录下没有传统桌面程序的 .rc 资源文件、主窗口类文件，反而不约而同地出现 tsconfig.json、vite.config.ts、tailwind.config.js。因为渲染进程的开发模式已经彻底 Web 化了，桌面窗口里住的其实是一套标准的前端工程。

2.4 IPC 接口放在哪里，最能看出一个项目是“顺手写”还是“认真设计”

现代桌面应用主进程和渲染进程之间通过 IPC 通信。IPC 接口的命名、注册位置、类型声明散落在哪个目录，直接反映了项目的组织水平。

初级项目经常把事件名直接用字符串写在页面按钮里：window.electronAPI.writeFile('/tmp/x.txt')。初跑没问题，可一旦要加权限、做类型约束、统一错误处理，就发现字符串到处都是，错误排查完全靠肉眼搜索。

好一点的项目会在 shared/ 里预先定义 channel 常量，比如：

ts复制export const IpcChannels = {
  FileSelect: 'file:select',
  FileWrite: 'file:write',
  SettingsLoad: 'settings:load',
} as const

然后在 src/main/ipc/handlers/ 里注册对应处理函数，渲染进程通过 src/renderer/src/api/ 里封装的函数统一调用。目录上的分工其实是这样的逻辑线：

• shared/：进程之间共享的常量、类型，IPC 两端都不会直接跑业务逻辑。
• src/main/ipc/：IPC 真正干活的那一端，负责校验参数、调用服务、返回结果。
• src/renderer/src/api/：渲染进程对外的封装，页面组件不直接写 ipcRenderer.invoke。

页面组件只依赖 api/ 层，api/ 层只依赖 shared/ 里的 channel 和类型，主进程 handler 也依赖同一份类型。这样即使以后把某个 IPC 换成 HTTP 接口，页面代码也几乎不用动，目录边界的价值就体现在这种地方。

3. src、public、dist：构建规则是从 Web 工程搬过来的，但用法不完全一样

3.1 输入输出分离：src 是原料，dist 是产品

不管 Electron 还是 Tauri，现代桌面应用都继承了 Web 构建的核心理念：源文件目录与构建产物目录严格分离。

src 下是人写的 TypeScript、CSS、组件、HTML，dist/ 或 out/ 下是经过编译、打包、压缩后可以运行的代码。构建过程本身是可重复的，任何人 clone 代码后执行 npm install && npm run dev，都能在当前机器上重新生成一套和自己环境匹配的产物。

这一点看起来平平无奇，但在传统桌面开发里并不都是这么做的。老式 Visual Studio 工程会把 .obj、.pdb 等中间文件放在项目目录里的 Debug/、Release/ 子目录，有时还会产生大量杂散的编译缓存文件。团队协作时，如果 .gitignore 配置不到位，这些二进制中间文件会源源不断进入版本库，导致代码库越来越脏。

现代目录结构把“人写的代码”和“机器生成的产物”从物理上隔离开来，也意味着开发态和运行态不再共享同一份数据。开发中你改了代码，热更新可能直接生效；但要发布给用户，必须重新构建并走一次打包流程。原因就是因为 dev 模式下的源码引用关系和生产模式的产物路径并不一致，这个边界如果混淆，就会出现“我本地跑得好好的，装到别人电脑上白屏”的局面。

3.2 public 和 assets 的区别：哪些资源会被“加工”，哪些不会

渲染进程目录里常见的 public 其实很容易被误解。很多人以为它就是手机 App 里的“公共资源目录”，啥都可以往里丢。实际上它对构建工具的含义很明确：public 下的内容不会被编译、不会被 hash、不会被压缩，原样复制到输出目录的根路径下。

与之相对的是放 src/assets 下的图片、字体、样式，它们经过构建工具处理，可能被压缩、被改名、被打进 CSS 文件里。

具体到桌面项目，推荐放进 public 的是：favicon.ico、启动页 loading.html、PWA 用的 manifest.json、机器人协议、一些需要在运行时动态引用的静态文件。推荐放进 assets 的是：组件里用到的图片、SVG 图标、自定义字体、基础样式里的背景图。

注意事项是路径写法。在 Web 端你习惯了 public/logo.png 可以直接用 /logo.png 引用，但 Electron 生产环境下页面是从 file:// 协议加载的，根路径并不是网站的域名根。如果 index.html 里写死了绝对路径 /logo.png，在某些壳里能加载成功，有些壳里就找不到文件。比较稳的做法是构建时让 Vite 处理资源引用，而不是手工把路径写进 HTML 里；实在需要动态指向 public 下的文件时，尽量通过 import.meta.env.BASE_URL 或绝对路径拼接，避免踩路径坑。

3.3 打包之后还会再多一层 resources，别把它和源码目录搞混

构建完成后的应用，目录结构会再变一次，变成“运行时视角”的结构。以典型 Electron 应用为例，安装完成后你会看到：

code复制MyApp/
├── MyApp.exe             # 可执行文件壳
├── resources/
│   ├── app.asar          # 应用源码归档包
│   ├── icon.ico
│   └── extra-assets/     # 额外资源
└── locales/
    └── zh-CN.pak

很多人第一次排查生产环境问题时，会在安装目录里找 src/renderer/index.html，找不到就很慌。其实源码已经被打进 app.asar 里了，这个文件是 Electron 专用的归档格式，里面就是 src 编译后的产物。开发时我们看的是源码目录树，运行时应用读的是 app.asar 内部的抽象文件树，两者并不一一对应。

这带来一个很容易踩的坑：主进程代码里如果用了 __dirname 去拼资源路径，开发时指向的是你仓库里的某个目录，打包后却可能指向 resources/app.asar/src/main。而有些资源文件没有被打进 asar，实际落在 resources/ 外面的真实路径。这种“源码目录结构”和“运行时文件结构”不一致的情况，是桌面应用路径问题最典型的来源。解决方法是尽量用框架提供的 app.getAppPath()、process.resourcesPath 代替手工拼路径，不要把相对路径写死。

从研发到交付，一套代码实际上有两条目录树：一条是方便人读写的源码树，一条是运行时必需的产物树。理解它们的差别，比记住某个具体文件放哪更重要。

4. 从 Java Web 时代走过来的开发者，怎么看这份“怪异”的目录

4.1 你熟悉的工程结构，其实都可以映射到现代桌面项目里

去年一个用 IDEA 建 Java Web 项目、在 JSP 页面里用 JS + JQuery 写审批流界面的同事，第一次看 Electron 项目吐槽说“这是把前端项目和后端项目揉在一起了”。这个观感不算错，但如果仔细对照，会发现现代桌面应用并不是简单揉，而是把 Web 开发里“前后端分离”的思路重新在本地进程里实现了一遍。

传统 Java Web 工程一般长这样：

code复制approval-webapp/
├── pom.xml
├── src/main/java/
│   └── com/company/approval/
│       ├── controller/
│       ├── service/
│       └── mapper/
├── src/main/webapp/
│   ├── WEB-INF/
│   ├── jsp/
│   │   └── approvalForm.jsp
│   └── static/
│       ├── css/
│       └── js/
└── target/

到现代桌面应用里，controller 的职责被拆成了两层：处理渲染进程发来的 IPC 消息、以及处理调用远程 Web API 的请求。页面模板 jsp 的职责则由 renderer/pages/ApprovalForm.vue 取代。static/css 和 static/js 对应到渲染进程的资源目录。真正新增的是那些负责系统集成的主进程服务，它承担了原本不存在于 Web 工程里的窗口、原生菜单、本地文件库等能力。

这样看就不会慌了：你不是丢掉过去的架构知识，只是把“服务端 Controller”的一部分转化成“主进程 IPC Handler”，把“浏览器里的页面”整体迁移到渲染进程。目录结构多出来的那几个顶层文件夹，本质上是对本地进程边界和远程服务边界做的显式声明。

4.2 一个审批流程从浏览器搬到桌面的目录级改造

设想一下：原来有一个 Web 审批系统，前端页面提交表单后调用后端的 /api/approval/submit 接口。后端 Controller 接收参数，存入数据库，然后给管理员发通知。

现在要改成桌面客户端，但希望兼容原有后端服务，目录会怎么动？如果保留现有 Java Web 服务，桌面端只需要把登录和接口调用逻辑写到渲染进程的 api/ 模块里，页面展示还是原来那套 React/Vue 代码。管理员通知不再走浏览器通知，而是希望点开系统托盘图标就能看到待办，那这部分能力得通过 IPC 交到主进程，由主进程调起系统通知或更新托盘菜单。

此时目录里典型会出现：

text复制src/renderer/src/api/approval.ts       // 封装 HTTP 请求，逻辑与 Web 端完全一致
src/renderer/src/pages/ApprovalForm.vue // 表单界面
src/main/ipc/handlers/approval.ts      // 处理渲染进程的本地待办请求
src/main/services/notify.ts            // 系统通知、托盘更新
shared/types/approval.ts               // IPC 与 HTTP 共用的审批状态类型

你可以发现，如果把 src/main 理解为“部署在用户电脑上的微型后端”，把 src/renderer 理解为“部署在本地浏览器里的前端”，那这套目录结构只是传统前、后端分离架构的本地重演。差别是原来的 Tomcat、数据库、文件服务器可能要剥离开，能放云端的继续走 HTTP，不能放云端的本地能力才留在主进程。

4.3 一份代码里藏着多个“子应用”目录，是现代项目的常态

再往前一步，很多企业应用的桌面端并不仅仅是一个窗口，它可能还带独立的 Web 管理后台、配套的浏览器端页面、甚至一个给运维看的本地控制面板。这时候只靠 src 三层分区就不够了，项目外层会演化出更明显的仓库边界：

code复制enterprise-suite/
├── apps/
│   ├── desktop/        # 桌面客户端
│   ├── web-admin/      # Web 管理后台
│   └── console/        # 运维/调试控制台
├── packages/
│   ├── shared-types/
│   ├── ui-kit/
│   └── api-client/

这种 monorepo 结构越来越常见。它背后的逻辑很朴素：同一个企业业务，Web 端和桌面端要共享一套类型、一套 UI 组件、一套 API 封装。假如把它们拆成多个互相独立的 Git 仓库，修改一个字段类型就得跨仓库同步，体验非常痛苦。

目录在这里就不仅仅是代码分类，而是知识的归属边界。页面组件只有在 packages/ui-kit 里维护一份，apps/desktop 和 apps/web-admin 才能共同受益。这也是为什么现代项目里目录结构会被当成架构治理工具来对待的原因。

5. 新项目初始化、老项目迁移时，这 5 个目录细节最值得先处理

5.1 先跑通脚手架目录，再谈“自定义”

现在创建一个现代桌面项目，主流选择是 electron-vite 或 Tauri 的官方脚手架。我见过不少人在模板生成后第一件事就是把目录结构改成自己熟悉的样子，结果越改越乱。原因很简单：脚手架目录结构是和配置文件强绑定的，入口路径、主进程 target、渲染进程 root、alias 映射全都指向预设目录。随意改文件夹名而不同步配置，轻则 dev server 挂掉，重则打包后找不到入口。

正确顺序是先按照模板目录跑通一个“能打开窗口的最小版本”，感受一下每层文件夹的具体用途，再根据自己的业务需要做微调。比如模板里 src/renderer/src 下没有按业务拆 modules，你可以新增 modules/approval/ 这样的业务目录，但根目录的 main、preload、renderer 这三段不要动。因为它们对应的是构建工具的三个入口，动了就要连配置文件一起改，风险太高。

5.2 给自己定一套“不后悔”的目录命名规则

命名这种东西没有绝对标准，但有一个很实用的原则值得参考：让一个刚进项目的人，不读文档也能猜到大目录里放什么。我自己比较推荐的桌面项目内层规则是这样的：

再补充一点：不要把工具函数一股脑全放进 utils。桌面应用里大多数工具函数其实是某个服务的私有实现，硬凑一个全局 utils/index.ts 会让目录变得很虚。按服务模块就近放，等确实出现跨模块复用再提升到 packages 或 shared，这样目录的聚合度更高。

5.3 排查白屏和路径问题，先看目录层级对不对

桌面应用上线后最常见的两类问题，一是白屏，二是某个图片/配置文件找不到。从目录结构入手可以快速缩小范围。

第一类白屏，先从 out/renderer/index.html 是否存在判断构建产物是否完整。再打开 DevTools 看报错，如果报错是找不到构建入口 JS，大概率是渲染进程的加载路径在 dev 和 prod 之间切换时没有处理正确。新版 electron-vite 一般用 ELECTRON_RENDERER_URL 环境变量区分，路径不通时先查这个值。

第二类资源找不到，先确认目标资源到底应该放在 resources、public 还是用户数据目录里。固定不变的图标、字体、模板文件放 resources 或者打包进 asar；构建时需要被处理的静态资源放 public；运行时要写出的配置、缓存、下载文件，放在 app.getPath('userData') 下面。如果代码里明明写的是“读取本地配置文件”，配的路径却在安装目录下，那基本已经埋雷了——安装目录对普通用户通常是只读的，程序一更新你放进去的东西就没了。

5.4 “用户数据目录”和“安装目录”是两棵不一样的树

涉及桌面运维时，很多人会把“应用目录”和“用户数据目录”混为一谈。实际上现代桌面应用最重要的一个目录结构认知是：安装目录不一定有写权限，能长期写数据的应该是 OS 为每个用户单独开辟的数据目录。

举个例子，Electron 应用默认的用户数据目录在 Windows 上是 %APPDATA%/AppName，在 macOS 上是 ~/Library/Application Support/AppName，Linux 上一般是 ~/.config/AppName。数据库、配置文件、缓存、日志都应该放里面。Chromium 内核还会在 userData 目录下生成 Cache、GPUCache 这些子目录——这其实就是 Linux 下 Web 缓存机制在桌面端的延续。

这个区分对运维脚本影响特别大。老式桌面软件升级，运维习惯是“找到安装目录，整体替换 exe”，但对现代桌面应用，如果直接把整个安装目录删了再重装，用户数据还在还好说，要是安装目录里混着旧版映射出来的数据，删掉就全丢了。负责更新的人应该明白：卸载或替换安装包，不会自动抹掉 userData 下的配置和数据；反过来，单独清数据目录往往能解决打不开、白屏、状态异常的问题，不需要重装软件。

这也是为什么“桌面运维助手”类工具在处理现代应用故障时，第一步往往不是动安装目录，而是先看缓存和数据目录，再用安全模式重置渲染进程状态。换目录结构之后，排障思路也得跟着换。

5.5 加载 Web 视图出错时，目录结构提供的排查线索

现在很多桌面应用内置了第三方 Web 页面或 WebView 模块。遇到“加载 Web 视图时出错”“Service Worker 注册失败”这类报错，错误信息本身往往帮不了太多，但目录能提供线索。

先看这个页面是从哪里加载的：是打包进 resources 的本地离线页，还是从远程服务器拉取的在线页？如果是本地页，路径对不对、资源有没有被正确打进 resources，是首要排查项。如果是远程页，Service Worker 缓存策略、CSP 是否允许注册 Worker、userData 目录权限是否正常，都有可能成为根因。

这种源码目录、安装目录、userData 目录三者并存的局面，就是现代桌面应用的运行真相。调试时先在目录层面把每一棵树的位置弄清楚，再动手改代码，会少走很多弯路。

我现在的个人习惯是：拿到一个新桌面项目，不管技术栈是 Electron 还是 Tauri，先不急着跑 npm install。我会先在文件树里把四件事找全：主进程入口在哪个文件、渲染进程入口在哪、preload 暴露了哪些 API、shared 里有哪些共享类型。这四个点定位完，整个应用的骨架基本就清楚了。目录结构不是文档，但它比文档更少撒谎。如果你也在从 Web 往桌面端迁移，或者在阅读一个全新的桌面仓库时被目录弄得晕头转向，希望这篇文章能帮你找到一条清晰的阅读路径。