31.1 路径问题：开发环境与打包后路径不一致

在 Electron 开发中，有一个几乎每个新手都会踩到的坑：同样的代码，在本地 npm run dev 时跑得好好的，一打包成安装包就报错找不到文件、图片裂开、数据库连接失败。这背后的根本原因，是开发环境与生产环境下的工作目录和资源路径结构完全不同。

28.1.1 问题从何而来

开发时，你通常使用 electron . 或某个开发服务器（比如 Vite 的热更新服务）来启动应用。当前工作目录（process.cwd()）就是项目根目录，也就是 package.json 所在的文件夹。所以你常常会写类似这样的代码：

// 主进程中读取一个配置文件
const config = require('./config/app.json');

// 渲染进程中引用一张本地图片
<img src="./assets/logo.png" />

在这种场景下，相对路径的解析基准就是你当前执行 npm run dev 的目录，一切都能正确找到。

然而，一旦你将应用打包成 .exe、.dmg 或 .app，Electron 会把所有资源文件压缩到一个 app.asar 归档包中（除非你明确排除某些文件）。安装后的应用在运行时，process.cwd() 通常指向操作系统给程序的默认工作目录（可能是用户主目录、应用安装目录，甚至是一个临时文件夹），而不再是项目源码的根目录。同时，app.asar 中的文件结构对文件系统并不直接可见，你无法使用 fs.readFile 直接通过之前的相对路径访问到它们。

这时，所有硬编码的相对路径都会失效——图片加载不出来、JSON 文件读不到、自定义字体不显示。更麻烦的是，不同操作系统下默认的工作目录还不一样：Windows 下可能是 C:\Program Files\YourApp，macOS 下可能是 /Users/用户名 或 .app 包内部的 Resources 目录。

28.1.2 正确的路径处理方式

Electron 提供了一套专门用于解决这个问题的 API：app.getAppPath()、app.getPath(name)、__dirname 以及 process.resourcesPath。你需要根据资源类型，选择对应的取路径方式。

1. 主进程中的文件读取

在主进程中，永远不要依赖 process.cwd() 或拼接 ./ 来读写项目内的文件。应当使用 __dirname（CommonJS）或 import.meta.url（ESM）结合 app.getAppPath() 来定位。

__dirname 在打包后依然指向当前执行脚本所在的目录（在 app.asar 内的真实路径），因此可以这样安全地加载相邻文件：

const path = require('path');
const fs = require('fs');

// 读取与当前主进程脚本同目录下的 config.json
const configPath = path.join(__dirname, 'config.json');
const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));

如果你需要从应用根目录出发：

const { app } = require('electron');
const rootPath = app.getAppPath(); // 开发时是项目根目录，打包后是 app.asar 的根目录
const dbPath = path.join(rootPath, 'data', 'init.sql');

2. 加载 HTML 文件或前端资源

BrowserWindow.loadFile 也同样需要绝对路径。使用 __dirname 拼接是最稳妥的做法：

const mainWindow = new BrowserWindow({ /* ... */ });
mainWindow.loadFile(path.join(__dirname, 'renderer', 'index.html'));

如果你使用的是 loadURL 加载本地打包后的 Web 应用，也需要基于 __dirname 或 app.getAppPath() 构造文件协议路径。

3. 渲染进程中的资源引用

渲染进程中的 HTML/CSS/JS 最终也是从本地文件加载的，因此引用同目录下的图片、字体等，可以直接使用相对路径，但前提是这些资源与 HTML 文件保持相对位置不变。打包工具（如 Webpack、Vite）通常会把静态资源输出到同一目录下，所以这种情况通常无需额外处理。

更推荐的做法是使用 Webpack 的 publicPath 或 Vite 的 base 配置为相对路径（'./'），确保打包后的资源链接从当前 HTML 文件的目录开始解析，这样无论应用安装在哪里，资源都能正确找到。

// vite.config.js
export default {
  base: './',
};

4. 用户数据与可写文件

配置、数据库、日志这类需要在运行时写入的文件，绝对不能放在应用安装目录内（因为安装目录通常是只读的，而且会在升级时被覆盖）。应使用 app.getPath('userData')，它会返回操作系统规定的用户专属数据目录（Windows: %APPDATA%，macOS: ~/Library/Application Support，Linux: ~/.config）。示例：

const userDataPath = app.getPath('userData');
const dbPath = path.join(userDataPath, 'mydb.sqlite');

5. 需要排除出 asar 的静态资源

如果你有大体积的二进制工具（如 ffmpeg.exe）需要在运行时调用，或者需要动态 require 的原生 Node.js 模块，这些文件不能打包进 app.asar（因为 asar 内不能执行二进制程序）。你需要在打包配置中将它们排除，并使用 process.resourcesPath 或 app.getAppPath().replace('.asar', '.asar.unpacked') 来定位这些文件。

例如，在 electron-builder 配置中：

"extraResources": [
  {
    "from": "extra-bin/",
    "to": "extra-bin"
  }
]

然后在主进程中引用：

const binPath = path.join(process.resourcesPath, 'extra-bin', 'ffmpeg.exe');

28.1.3 一个统一的最佳实践

为了避免路径问题在各个地方反复出现，建议在项目中建立一个专用的工具函数：

// utils/paths.js
const path = require('path');
const { app } = require('electron');

function getAppRoot() {
  return app.getAppPath();
}

function getResourcePath(relativePath) {
  return path.join(getAppRoot(), relativePath);
}

function getUserDataPath(relativePath) {
  return path.join(app.getPath('userData'), relativePath);
}

module.exports = { getAppRoot, getResourcePath, getUserDataPath };

然后在所有需要路径的地方统一调用这些函数，彻底告别 './config.json' 这样的写法。

28.1.4 实战经验总结

开发环境与打包后的路径差异不是 Bug，而是设计使然。Electron 必须使用 asar 归档和独立的工作目录来保证安装包的安全性与可升级性。
不要依赖 process.cwd()。在 Electron 中它的值是不可预期的，把它忘掉。
所有只读的、随应用代码一起发布的资源，使用 __dirname 或 app.getAppPath() 拼绝对路径。
所有需要在运行时修改的数据，使用 app.getPath('userData') 存放。
处理跨平台差异还要注意路径分隔符，使用 Node.js 的 path.join() 而不是手动拼接字符串，它能自动处理正斜杠和反斜杠。

当你把这些规则内化后，“开发时正常、打包后失效”的问题就会从你的项目里彻底消失，这也是一个成熟 Electron 开发者的基本功。