ToolKit Pro 专业开发者的全能工具箱 - 源码编译

ToolKit Pro 源码编译完整指南

本文档详细介绍如何从源码编译构建 ToolKit Pro 桌面应用程序

📋 目录

• 环境要求
• 源码获取
• 依赖安装
• 开发环境配置
• 编译构建
• 打包发布
• 常见问题
• 开发指南
• 贡献代码

🔧 环境要求

在开始编译之前，请确保您的开发环境满足以下要求：

基础环境

组件	版本要求	说明
Node.js	>= 18.0.0	推荐使用最新的LTS版本
npm	>= 8.0.0	通常随Node.js一起安装
Git	>= 2.20.0	用于版本控制和源码获取

操作系统支持

• Windows: Windows 10 及以上版本
• macOS: macOS 10.15 (Catalina) 及以上版本
• Linux: Ubuntu 18.04+ / CentOS 8+ / Fedora 30+

开发工具推荐

• 代码编辑器: Visual Studio Code
• 终端工具: Windows Terminal / iTerm2 / GNOME Terminal
• 包管理器: npm (推荐) / yarn

📥 源码获取

ToolKit Pro Code-5464.rar

1. 查看项目结构

tree -I 'node_modules|dist*|release' -L 3

预期的项目结构：

toolkit-pro/
├── electron/              # Electron主进程和预加载脚本
│   ├── main.js            # Electron主进程
│   └── preload.js         # 预加载脚本
├── src/                   # React前端源码
│   ├── components/        # React组件
│   │   ├── tools/         # 工具组件
│   │   ├── Sidebar.jsx    # 侧边栏组件
│   │   └── TitleBar.jsx   # 标题栏组件
│   ├── App.jsx           # 主应用组件
│   ├── App.css           # 全局样式
│   ├── main.jsx          # React入口文件
│   └── index.css         # 基础样式
├── public/               # 静态资源
├── docs/                 # 文档目录
├── package.json          # 项目配置文件
├── vite.config.js        # Vite构建配置
├── index.html            # HTML模板
└── README.md             # 项目说明

📦 依赖安装

1. 安装Node.js依赖

# 使用npm安装依赖
npm install

# 或使用yarn安装（如果您使用yarn）
yarn install

2. 验证依赖安装

# 检查依赖是否正确安装
npm list --depth=0

# 验证关键依赖版本
npm list electron react vite

3. 主要依赖说明

核心依赖

{
  "electron": "^28.0.0",           // Electron框架
  "react": "^18.2.0",              // React框架
  "react-dom": "^18.2.0",          // React DOM操作
  "vite": "^5.0.0"                 // 前端构建工具
}

开发依赖

{
  "@vitejs/plugin-react": "^4.2.1", // Vite React插件
  "electron-builder": "^24.9.1",     // Electron打包工具
  "concurrently": "^8.2.2",          // 并发执行工具
  "wait-on": "^7.2.0"                // 等待服务启动工具
}

🛠️ 开发环境配置

1. 配置开发环境变量

创建 .env.development 文件：

# 开发环境配置
NODE_ENV=development
VITE_DEV_SERVER_PORT=5173
ELECTRON_IS_DEV=true

2. IDE配置推荐

Visual Studio Code 推荐插件

{
  "recommendations": [
    "ms-vscode.vscode-node-azure-pack",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-json",
    "formulahendry.auto-rename-tag"
  ]
}

ESLint 配置

项目已包含 eslint.config.js 配置文件：

import js from '@eslint/js'
import globals from 'globals'
import react from 'eslint-plugin-react'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'

export default [
  { ignores: ['dist'] },
  {
    files: ['**/*.{js,jsx}'],
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
      parserOptions: {
        ecmaVersion: 'latest',
        ecmaFeatures: { jsx: true },
        sourceType: 'module',
      },
    },
    settings: { react: { version: '18.2' } },
    plugins: {
      react,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    rules: {
      ...js.configs.recommended.rules,
      ...react.configs.recommended.rules,
      ...react.configs['jsx-runtime'].rules,
      ...reactHooks.configs.recommended.rules,
      'react/jsx-no-target-blank': 'off',
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true },
      ],
    },
  },
]

🔨 编译构建

1. 开发模式运行

# 启动开发服务器（热重载）
npm run dev

# 或分别启动前端和Electron
npm run dev:vite    # 仅启动Vite开发服务器
npm run dev:electron # 仅启动Electron

开发服务器启动后：

• Vite服务器运行在 http://localhost:5173
• Electron应用会自动启动并连接到开发服务器
• 支持热重载，修改代码后自动刷新

2. 生产环境构建

# 构建前端资源
npm run build

# 构建过程说明：
# 1. Vite 构建React应用到 dist/ 目录
# 2. 编译Electron主进程代码到 dist-electron/ 目录
# 3. 优化和压缩所有资源文件

构建产物目录结构：

dist/                    # 前端构建产物
├── index.html          # 入口HTML文件
├── assets/             # 静态资源
│   ├── index-*.css     # 样式文件
│   └── index-*.js      # JavaScript文件
└── vite.svg           # 图标文件

dist-electron/          # Electron构建产物
├── main.js            # 主进程文件
└── preload.js         # 预加载脚本

3. 预览构建结果

# 预览构建后的应用
npm run preview

# 或直接运行Electron应用
npm run electron

📱 打包发布

1. 打包配置

package.json 中的打包配置：

{
  "build": {
    "appId": "com.toolkit-pro.app",
    "productName": "ToolKit Pro",
    "directories": {
      "output": "release"
    },
    "files": [
      "dist/**/*",
      "dist-electron/**/*",
      "node_modules/**/*",
      "package.json"
    ],
    "mac": {
      "category": "public.app-category.developer-tools",
      "target": "dmg"
    },
    "win": {
      "target": "nsis"
    },
    "linux": {
      "target": "AppImage"
    }
  }
}

2. 跨平台打包

# 打包当前平台
npm run dist

# 打包Windows版本（在任意平台）
npm run dist:win

# 打包macOS版本（需要在macOS上）
npm run dist:mac

# 打包Linux版本（推荐在Linux上）
npm run dist:linux

# 打包所有平台（需要配置额外工具）
npm run dist:all

3. 打包产物

打包完成后，在 release/ 目录下会生成：

Windows

• ToolKit Pro Setup.exe - NSIS安装包
• ToolKit Pro.exe - 便携版可执行文件

macOS

• ToolKit Pro.dmg - macOS安装包
• ToolKit Pro.app - 应用程序包

Linux

• ToolKit Pro.AppImage - Linux便携应用
• ToolKit Pro.deb - Debian包（可选）
• ToolKit Pro.rpm - RedHat包（可选）

4. 代码签名（可选）

对于生产发布，建议配置代码签名：

Windows代码签名

{
  "win": {
    "certificateFile": "path/to/certificate.p12",
    "certificatePassword": "password",
    "publisherName": "Your Name"
  }
}

macOS代码签名

{
  "mac": {
    "identity": "Developer ID Application: Your Name",
    "notarize": true
  }
}

❗ 常见问题

1. 依赖安装问题

问题: npm install 失败或缓慢

解决方案:

# 清理npm缓存
npm cache clean --force

# 使用淘宝镜像
npm config set registry https://registry.npm.taobao.org/

# 或使用cnpm
npm install -g cnpm
cnpm install

2. Electron启动问题

问题: Electron窗口无法启动或白屏

解决方案:

# 检查端口占用
netstat -ano | findstr :5173

# 重新安装Electron
npm uninstall electron
npm install electron --save-dev

# 清理并重新构建
npm run clean
npm run build

3. 打包失败问题

问题: electron-builder 打包失败

解决方案:

# 检查网络连接和代理设置
npm config get proxy
npm config get https-proxy

# 设置Electron镜像（中国用户）
export ELECTRON_MIRROR=https://npm.taobao.org/mirrors/electron/

# 重新安装打包工具
npm uninstall electron-builder
npm install electron-builder --save-dev

4. 跨平台打包问题

问题: 在Windows上打包macOS版本失败

解决方案:

• macOS应用需要在macOS系统上打包
• 使用CI/CD服务（如GitHub Actions）进行跨平台打包
• 配置虚拟机或云服务器

🔍 开发指南

1. 添加新工具组件

# 创建新工具组件
touch src/components/tools/YourNewTool.jsx

2. 注册新工具

在 src/App.jsx 中注册新工具：

// 1. 导入组件
import YourNewTool from './components/tools/YourNewTool'

// 2. 添加到工具映射
const tools = {
  // ... 其他工具
  'your-new-tool': { 
    title: 'Your New Tool', 
    component: YourNewTool, 
    category: 'text' // 选择合适的分类
  },
}

// 3. 添加到渲染函数
const renderTool = () => {
  // ... 其他工具case
  case 'your-new-tool':
    return <YourNewTool />
}

在 src/components/Sidebar.jsx 中添加菜单项：

const toolCategories = {
  // ... 其他分类
  text: [
    // ... 其他工具
    { id: 'your-new-tool', name: '您的新工具', icon: 'fas fa-tools' },
  ],
}

3. 添加Electron API

如果需要使用Node.js功能：

1. 在主进程添加API (electron/main.js)

// 添加IPC处理器
ipcMain.handle('your-api-name', async (event, ...args) => {
  try {
    // 使用Node.js API处理
    const result = await yourProcessFunction(...args);
    return { success: true, data: result };
  } catch (error) {
    return { success: false, error: error.message };
  }
});

2. 在预加载脚本暴露API (electron/preload.js)

contextBridge.exposeInMainWorld('electronAPI', {
  // ... 其他API
  yourApiName: (...args) => ipcRenderer.invoke('your-api-name', ...args)
});

3. 在React组件中使用

const handleUseElectronAPI = async () => {
  if (window.electronAPI) {
    const result = await window.electronAPI.yourApiName(param1, param2);
    if (result.success) {
      setOutput(result.data);
    } else {
      console.error(result.error);
    }
  }
};

2. 开发流程

# 1. 创建功能分支
git checkout -b feature/your-feature-name

# 2. 进行开发
# ... 编写代码 ...

# 3. 提交更改
git add .
git commit -m "feat: add your feature description"

# 4. 推送分支
git push origin feature/your-feature-name

# 5. 创建Pull Request

3. 代码规范

提交信息规范

feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建工具或辅助工具的变动

代码风格

• 使用ESLint进行代码检查
• 使用Prettier进行代码格式化
• 遵循React Hooks最佳实践
• 组件名使用PascalCase
• 文件名使用PascalCase

4. 测试要求

# 运行代码检查
npm run lint

# 修复可自动修复的问题
npm run lint:fix

# 运行构建测试
npm run build

# 运行应用测试
npm run test

📚 更多资源

官方文档

• Electron官方文档
• React官方文档
• Vite官方文档
• electron-builder文档

社区资源

• Electron开发最佳实践
• React性能优化指南
• Node.js API参考

问题报告

如果您在编译过程中遇到问题，请：

1. 检查本文档的常见问题部分
2. 搜索已有的GitHub Issues
3. 创建新的Issue，包含：
   • 操作系统和版本
   • Node.js和npm版本
   • 完整的错误日志
   • 重现步骤