# preload、上下文隔离与受限能力桥
## 为什么 preload 里能 require，页面里却不能
你可能已经遇到一个看似矛盾的现象：main.cjs 可以加载文件系统模块，preload.cjs 也写 require，却加载不了同样的模块；renderer.js 则连 require 都不存在。这不是安装坏了，而是三处代码处于不同权限环境。理解差别之后，才能决定某段代码应该放在哪里，而不是通过关闭安全选项让报错暂时消失。
本章前置是前面的窗口与进程关系，目标是准确解释 contextIsolation、sandbox 和 nodeIntegration 分别限制什么，并实现一个边界小、输入可验证的桥。本章桥只维护内存中的展示设置，不涉及磁盘、网络或 IPC；这样可以单独观察跨上下文复制与函数代理，不把下一章的进程通信混进来。
主进程拥有完整的 Node 环境；安全配置下的页面没有 Node 集成；沙箱 preload 获得一组受限的兼容接口，用来完成桥接。这组 require 是受限实现，不能因为名字与主进程一样，就推导它支持任意 Node 包或项目文件。运行环境决定能力，文件扩展名只影响代码解析方式的一部分。
## 三个选项解决三个不同层面的问题
contextIsolation 把 preload 与页面脚本放到不同的 JavaScript 世界。双方操作的是同一页面相关环境，但全局对象、内建对象与脚本变量不是随意共享的。隔离的价值，是让页面不能简单地修改 preload 所依赖的全局对象，再借它执行拥有更多权限的操作。它不是一个新进程，也不是让所有函数自动获得输入检查。
sandbox 限制 renderer 直接访问操作系统资源的能力。需要权限的工作通过明确通信交给更有权限的进程执行。nodeIntegration 决定页面是否获得 Node 集成；开启它会影响沙箱，因此不能把三个布尔值当成互不相关的独立功能开关。安全默认组合应保持页面没有 Node，preload 隔离，renderer 有沙箱。
当前默认值是 contextIsolation 为 true、sandbox 为 true、nodeIntegration 为 false。历史上前两项默认值曾改变，所以旧教程可能要求你显式开启，也可能直接关闭它们以使用老式写法。我们仍在示例中写清这三个值，是为了表达设计意图和便于审查，不是因为当前默认值不安全。不要把某个教程年代的默认值当成所有 Electron 版本的固定事实。
| 配置或边界 | 主要回答的问题 | 不会自动替你做的事 |
| --- | --- | --- |
| contextIsolation | 页面与 preload 是否隔离脚本世界 | 验证业务参数和用户授权 |
| sandbox | renderer 能否直接接触大部分系统资源 | 限制主进程自己暴露的危险能力 |
| nodeIntegration | 页面是否获得 Node 集成 | 让第三方脚本变可信 |
| contextBridge | 哪些值或函数跨隔离边界可见 | 把任意通用接口变成安全接口 |
将按钮暴露为 chooseNote() 与暴露 readFile(path) 有本质区别。前者可以在主进程中打开系统选择框，把权限限定为用户刚刚选中的文件；后者允许页面主动提出任意路径。即便两者都通过 contextBridge、都在沙箱内调用，后者仍然扩大了能力。安全配置提供底座，具体接口仍然由应用负责。
## 沙箱 preload 的 require 到底有哪些边界
当前官方文档列出沙箱 preload 可以访问 Electron 的一组 renderer 模块，以及 events、timers、url 等有限 Node 内建模块，也提供 Buffer、受限 process 和部分计时原语。它没有完整文件系统和子进程能力，也不支持把 preload 用普通 require('./helper.cjs') 随意拆成多个本地 CommonJS 文件。
这解释了一个常见迁移故障：开发者把 preload 里的参数检查提取到 helper.cjs，写法与 main 完全一样，却在窗口中得到加载失败。解决方向是让 preload 保持小而独立，或者在构建阶段把依赖打包成沙箱可执行的单文件。把 sandbox 改成 false 虽可能让旧结构工作，却改变了安全边界，不能作为默认教程答案。
.cjs 只明确 CommonJS 语法，不会把受限 require 升级成完整 Node。把文件改名为 .mjs 也不是通用解决办法，Electron 的 preload 模块支持与沙箱存在额外限制。本组故意使用小型 .cjs 文件，避免一开始引入 ESM 与打包器交互；以后引入构建时，应检查最终产物的运行环境，不只检查源文件能否通过编辑器类型检查。
## 实验一：离线验证模块许可规则
保存 require-policy.cjs，运行 node require-policy.cjs。这里实现的是一份课堂规则模型，不是 Electron 实际的模块加载器，也不是安全沙箱。我们把允许集合和拒绝行为写成显式断言，帮助你区分“函数叫 require”与“拥有完整 Node 模块系统”。
```js require-policy.cjs
'use strict';
const assert = require('node:assert/strict');
const allowed = new Set(['electron', 'events', 'timers', 'url']);
function sandboxRequirePolicy(name) {
if (typeof name !== 'string') return { ok: false, code: 'BAD_NAME' };
const normalized = name.startsWith('node:') ? name.slice(5) : name;
return allowed.has(normalized)
? { ok: true, module: normalized }
: { ok: false, code: 'MODULE_NOT_ALLOWED' };
}
assert.equal(sandboxRequirePolicy('electron').ok, true);
assert.equal(sandboxRequirePolicy('node:events').ok, true);
for (const name of ['node:fs', 'node:child_process', './helper.cjs', 'axios']) {
assert.equal(sandboxRequirePolicy(name).ok, false);
}
console.log('通过：内建许可集合与本地/第三方模块拒绝规则');
```
模型只验证模块名称集合；真实 Electron 对 electron 导出的模块还有具体范围，不能把本模型的 ok 理解成允许 Electron 包里所有主进程 API。比如 BrowserWindow 属于主进程，不能在 preload 中创建。我们在实际桥中只解构 contextBridge，越小的依赖范围越容易解释和维护。
## 实验二：观察静态快照与函数代理
建立 isolation-lab 目录，放入五个完整文件。页面可以修改一条内存标题，并读取当前快照；它不能获取完整 process、require 或任意通信通道。标题的最大长度在桥内验证，因此即使绕过输入框直接调用函数，也不能绕过合同。
```json package.json
{
"name": "electron-isolation-lab",
"version": "1.0.0",
"private": true,
"main": "main.cjs",
"scripts": { "start": "electron ." },
"devDependencies": { "electron": "44.3.0" }
}
```
```js main.cjs
'use strict';
const { app, BrowserWindow } = require('electron');
const path = require('node:path');
function createWindow() {
const win = new BrowserWindow({
width: 780, height: 520,
webPreferences: {
preload: path.join(__dirname, 'preload.cjs'),
contextIsolation: true, sandbox: true, nodeIntegration: false
}
});
win.webContents.on('will-navigate', event => event.preventDefault());
win.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
void win.loadFile(path.join(__dirname, 'index.html')).catch(error => {
console.error(error.message);
app.quit();
});
}
app.whenReady().then(() => {
createWindow();
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) createWindow();
});
}).catch(error => { console.error(error); app.quit(); });
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit();
});
```
```js preload.cjs
'use strict';
const { contextBridge } = require('electron');
let title = '初始标题';
let revision = 0;
function snapshot() {
// 每次构造新的普通数据对象，不返回内部可变容器。
return { title, revision };
}
function setTitle(value) {
if (typeof value !== 'string') {
return { ok: false, error: { code: 'BAD_TYPE', message: '标题必须是字符串' } };
}
const normalized = value.trim();
if (normalized.length < 1 || normalized.length > 40) {
return { ok: false, error: { code: 'BAD_LENGTH', message: '标题长度需为 1 到 40 个 UTF-16 单元' } };
}
title = normalized;
revision += 1;
return { ok: true, value: snapshot() };
}
contextBridge.exposeInMainWorld('titleSettings', {
initial: snapshot(), // 非函数值是公开时的快照，不会自动追踪 title
environment: {
sandboxed: process.sandboxed === true,
isolated: process.contextIsolated === true
},
read: snapshot,
setTitle
});
```
```html index.html
隔离与桥
标题设置
```
```js renderer.js
'use strict';
const api = window.titleSettings;
const result = document.querySelector('#result');
const status = document.querySelector('#status');
function render() {
result.textContent = JSON.stringify({
initial: api.initial,
current: api.read(),
environment: api.environment,
rendererRequire: typeof require
}, null, 2);
}
document.querySelector('#form').addEventListener('submit', event => {
event.preventDefault();
const reply = api.setTitle(document.querySelector('#title').value);
status.textContent = reply.ok ? '修改成功' : reply.error.message;
render();
});
render();
```
```sh
npm install
npm start
```
首次 npm install 下载固定 Electron 44.3.0 的桌面二进制；之后此应用运行无网络请求。预期初始与当前标题都为“初始标题”，提交后 current 更新且 revision 增加，initial 仍保持最初内容；environment 两项为 true，rendererRequire 为 undefined。输入空白时返回长度错误而不修改状态。这些为真实 GUI 的验收步骤，本轮只检查脚本语法和离线规则。
## 为什么修改 current 不会让 initial 跟着变
contextBridge 对非函数值采用复制并冻结的方式，对函数建立可调用的代理。公开 initial 时获得的是当时的数据快照，不是响应式引用。以后 title 改变，页面需要再调用 read 得到新结果。你在 Vue 中习惯的 reactive 依赖追踪，不会跨这个桥自动传播；桥定义的是外部接口，不是共享组件状态。
函数代理也不意味着页面拿到了函数的闭包变量。页面只能调用 setTitle，函数仍在其所属上下文执行，内部 title 没有被直接公开。这个机制让我们可以把允许的变化集中到少数方法里，并在方法入口检查类型和范围。公开一个可任意调用名称的 call(method, args) 则会失去这种可审查性。
示例的 setTitle 是同步操作，因为它只改变极小的本地内存状态。磁盘、系统对话框和网络应通过下一章的异步 IPC 方法完成。把耗时循环放到这个代理函数中仍然可能卡住 renderer，它不自动转移到主进程或后台线程。函数跨世界与工作跨进程是两件独立的事。
这里 revision 表示设置成功修改次数，不是全局唯一版本，也没有持久化和并发冲突处理。页面刷新后 preload 重新执行，状态回到初始值。将它用于真实应用设置时，应由持久化层拥有权威状态，桥只负责访问合同；不要误把 preload 闭包当成跨窗口共享数据库。
## 输入验证的位置与错误语义
输入框的 maxlength 改善交互，却不能成为唯一限制。页面脚本可以直接调用 setTitle，或者未来换成另一个组件，绕过输入框属性。桥中重复验证可以提早提供一致错误；若操作最终进入主进程，主进程还需要自己的验证，因为桥不是唯一可以假定永远正确的安全边界。
例子把字符串长度明确写为 UTF-16 单元，是因为 JavaScript length 对某些表情会计为两个或更多单元。若业务要求“用户看见的字符数”，需要采用相应分段规则，不能把 length 的结果含糊称为所有语言通用的字数。约束越具体，页面提示、校验和测试越容易保持一致。
错误使用普通对象和稳定 code，而不是让页面解析某段异常文字。BAD_TYPE 与 BAD_LENGTH 都不会修改状态，因此调用者可以安全保留当前展示。对于不可预期的程序错误，仍然应该记录诊断信息并修复，不应把所有错误都伪装成用户输错。业务失败与编程缺陷分开，才不会出现“所有按钮都提示重试，但真正原因无从定位”。
## 实验三与练习：做一个只有两项能力的设置合同
练习要求接收 {theme, fontSize}，主题只允许 light 或 dark，字号是十二到三十二之间的整数，拒绝额外字段。返回新的普通对象，不能保留调用者传入的可变引用。提示是先检查对象形状，再检查字段值，不要通过默认合并把未知字段带入内部状态。
参考答案：完整设置校验与回归
保存 settings-contract.cjs，运行 node settings-contract.cjs，无需依赖。
```js settings-contract.cjs
'use strict';
const assert = require('node:assert/strict');
function validateSettings(input) {
const fail = code => ({ ok: false, error: { code } });
if (!input || typeof input !== 'object' || Array.isArray(input)) return fail('BAD_OBJECT');
const keys = Object.keys(input);
if (keys.length !== 2 || !keys.includes('theme') || !keys.includes('fontSize')) {
return fail('BAD_FIELDS');
}
if (!['light', 'dark'].includes(input.theme)) return fail('BAD_THEME');
if (!Number.isInteger(input.fontSize) || input.fontSize < 12 || input.fontSize > 32) {
return fail('BAD_SIZE');
}
return { ok: true, value: { theme: input.theme, fontSize: input.fontSize } };
}
const source = { theme: 'dark', fontSize: 18 };
const reply = validateSettings(source);
source.fontSize = 30;
assert.equal(reply.value.fontSize, 18);
assert.equal(validateSettings({ theme: 'dark', fontSize: 18, path: '/tmp' }).ok, false);
assert.equal(validateSettings({ theme: 'dark', fontSize: 18.5 }).ok, false);
assert.equal(validateSettings(null).ok, false);
assert.equal(validateSettings({ theme: 'system', fontSize: 18 }).ok, false);
console.log('通过：字段、枚举、整数范围和复制边界');
```