From 34c370cbc274e13095025b028b5e829e12208db3 Mon Sep 17 00:00:00 2001 From: root Date: Sat, 22 Nov 2025 22:36:37 +0800 Subject: [PATCH] chore: init electron shell with cnpm setup --- .gitignore | 12 ++++ eletron项目开发方案.md | 136 +++++++++++++++++++++++++++++++++++++++++ main.js | 30 +++++++++ package.json | 39 ++++++++++++ 4 files changed, 217 insertions(+) create mode 100644 .gitignore create mode 100644 eletron项目开发方案.md create mode 100644 main.js create mode 100644 package.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c0a5acf --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +node_modules/ +dist/ +out/ +*.log +*.tmp +*.cache +*.map +.DS_Store +Thumbs.db +coverage/ +.env +*.local \ No newline at end of file diff --git a/eletron项目开发方案.md b/eletron项目开发方案.md new file mode 100644 index 0000000..eb4dd47 --- /dev/null +++ b/eletron项目开发方案.md @@ -0,0 +1,136 @@ +# Electron 项目开发方案 + +## 1. 项目目标 +- 使用 Electron 开发一个桌面“框架程序” +- 主程序启动后自动打开指定 Web 应用（示例：`https://www.baidu.com`） +- 程序窗口自动全屏并隐藏菜单栏 +- 支持在 Windows 与 Ubuntu 22 上打包与运行 + +## 2. 技术栈与工具 +- 核心：`Electron` +- 打包：`electron-builder` +- 运行环境：`Node.js LTS`（建议 18 或 20） +- 版本管理：`npm` + +## 3. 环境准备 +- 通用：安装 Node.js LTS +- Windows：建议安装 Git；如需原生模块构建，安装 Visual Studio Build Tools +- Ubuntu 22： + - `sudo apt update` + - `sudo apt install -y build-essential libarchive-tools rpm xz-utils libfuse2` + +## 4. 目录结构（最小可运行） +``` +项目根目录/ +├─ main.js +└─ package.json +``` + +## 5. 初始化步骤 +- 在项目根执行： + - `npm init -y` + - `npm i -D electron electron-builder` +- 准备主进程入口文件 `main.js` 与打包配置 `package.json` + +## 6. 核心实现 +### 6.1 主进程入口：`main.js` +```js +const { app, BrowserWindow } = require('electron') + +function createWindow() { + const win = new BrowserWindow({ + fullscreen: true, + autoHideMenuBar: true, + webPreferences: { + contextIsolation: true, + nodeIntegration: false, + sandbox: true + } + }) + win.loadURL('https://www.baidu.com') +} + +app.whenReady().then(() => { + createWindow() + app.on('activate', () => { + if (BrowserWindow.getAllWindows().length === 0) createWindow() + }) +}) + +app.on('window-all-closed', () => { + if (process.platform !== 'darwin') app.quit() +}) +``` + +### 6.2 打包与运行配置：`package.json` +```json +{ + "name": "electron-webshell", + "version": "0.1.0", + "main": "main.js", + "private": true, + "scripts": { + "start": "electron .", + "build": "electron-builder", + "build:win": "electron-builder --win", + "build:linux": "electron-builder --linux" + }, + "devDependencies": { + "electron": "^31.2.0", + "electron-builder": "^24.9.4" + }, + "build": { + "appId": "com.example.webshell", + "productName": "WebShell", + "files": [ + "main.js", + "package.json" + ], + "win": { + "target": ["nsis"], + "artifactName": "${productName}-Setup-${version}-${arch}.exe" + }, + "linux": { + "target": ["AppImage", "deb"], + "category": "Utility", + "artifactName": "${productName}-${version}-${arch}.${ext}" + } + } +} +``` + +## 7. 开发与调试 +- 启动开发模式：`npm start` +- 验证：程序启动后是否全屏、是否自动打开 `https://www.baidu.com` + +## 8. 打包与发布 +### 8.1 Windows 打包 +- 在 Windows 上执行：`npm run build:win` +- 产物位置：`dist/WebShell-Setup--.exe` +- 安装并运行验证：全屏展示且加载指定网页 + +### 8.2 Ubuntu 22 打包 +- 在 Ubuntu 22 上执行：`npm ci` +- 执行打包：`npm run build:linux` +- 产物位置： + - `dist/WebShell--.AppImage` + - `dist/WebShell--.deb` +- 运行验证： + - `chmod +x dist/WebShell--.AppImage && ./dist/WebShell--.AppImage` + - 或安装 `deb`：`sudo dpkg -i dist/WebShell--.deb` + +## 9. 安全与行为约束 +- 保持 `nodeIntegration: false`，避免网页直接访问 Node 能力 +- 使用 `contextIsolation: true` 与 `sandbox: true`，降低宿主风险 +- 仅加载受信任站点；如需内网地址，将 `loadURL` 改为目标内网 URL + +## 10. 常见问题与建议 +- 跨平台打包：建议在目标操作系统上本地打包（Windows 在 Windows，Linux 在 Ubuntu） +- 网络限制：如外网受限，改为内网地址；或将前端应用打包为本地资源并 `loadFile` +- Ubuntu 22 下 AppImage 运行异常：安装 `libfuse2` +- 无边框与更强锁定：可将 `fullscreen: true` 改为 `kiosk: true` + +## 11. 后续迭代方向 +- 启动参数或配置文件化：支持自定义 URL、窗口模式 +- 预加载脚本与白名单通信：在受控场景中安全地与网页交互 +- 自动更新：集成更新服务以便统一升级 \ No newline at end of file diff --git a/main.js b/main.js new file mode 100644 index 0000000..f2103ce --- /dev/null +++ b/main.js @@ -0,0 +1,30 @@ +const { app, BrowserWindow } = require('electron') + +if (process.env.ELECTRON_IGNORE_CERT_ERRORS === '1') { + app.commandLine.appendSwitch('ignore-certificate-errors') +} + +function createWindow() { + const win = new BrowserWindow({ + fullscreen: false, + autoHideMenuBar: true, + webPreferences: { + contextIsolation: true, + nodeIntegration: false, + sandbox: true + } + }) + const targetUrl = process.env.APP_URL || 'https://www.baidu.com' + win.loadURL(targetUrl) +} + +app.whenReady().then(() => { + createWindow() + app.on('activate', () => { + if (BrowserWindow.getAllWindows().length === 0) createWindow() + }) +}) + +app.on('window-all-closed', () => { + if (process.platform !== 'darwin') app.quit() +}) \ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..2f9d7fe --- /dev/null +++ b/package.json @@ -0,0 +1,39 @@ +{ + "name": "electron-webshell", + "version": "0.1.0", + "main": "main.js", + "private": true, + "scripts": { + "start": "electron .", + "build": "electron-builder", + "build:win": "electron-builder --win", + "build:linux": "electron-builder --linux" + }, + "devDependencies": { + "electron": "^31.7.7", + "electron-builder": "^24.13.3" + }, + "build": { + "appId": "com.example.webshell", + "productName": "WebShell", + "electronDist": "./node_modules/electron/dist", + "files": [ + "main.js", + "package.json" + ], + "win": { + "target": [ + "nsis" + ], + "artifactName": "${productName}-Setup-${version}-${arch}.exe" + }, + "linux": { + "target": [ + "AppImage", + "deb" + ], + "category": "Utility", + "artifactName": "${productName}-${version}-${arch}.${ext}" + } + } +}