Nativefier API 详解：从命令行到程序化接口的完整指南

Nativefier API 详解：从命令行到程序化接口的完整指南

nativefier Make any web page a desktop application 项目地址: https://gitcode.com/gh_mirrors/na/nativefier

前言

Nativefier 是一个强大的工具，它能够将任何网站快速打包成桌面应用程序。本文将深入解析 Nativefier 的 API 接口，帮助开发者全面掌握其功能特性，从基础使用到高级定制。

核心概念

Nativefier 的核心是将网页应用封装为桌面应用，基于 Electron 框架实现。它提供了两种主要使用方式：

1. 命令行接口（CLI）：通过终端命令快速创建应用
2. 程序化接口（API）：通过 JavaScript 代码进行更灵活的定制

命令行接口详解

基础命令结构

nativefier [选项] [目标网址] [输出目录]

必须提供以下两者之一：

• 目标网址（用于创建新应用）
• --upgrade 选项（用于升级现有应用）

关键参数说明

目标网址

指定应用要访问的网页地址。

输出目录

指定应用构建的输出位置。默认是当前目录，或环境变量 NATIVEFIER_APPS_DIR 指定的路径。

实用技巧：在 shell 配置文件中设置默认输出目录：

export NATIVEFIER_APPS_DIR=~/Applications/

应用创建选项

架构选择 (--arch)

指定目标处理器架构：

• 可选值：x64、armv7l、arm64、universal
• 注意区分平台（--platform）和架构的概念

图标设置 (--icon)

不同平台要求不同格式：

• Windows：.ico 文件
• Linux：.png 文件
• macOS：.icns 或 .png（需安装转换工具）

便携模式 (--portable)

使应用数据存储在应用目录内，便于携带。但需注意安全风险：共享应用时会包含所有用户数据。

升级现有应用 (--upgrade)

升级已有 Nativefier 应用到最新版本。注意这是原地升级，建议先备份。

窗口控制选项

窗口大小与位置

• --width/--height：初始尺寸
• --min-width/--max-height 等：限制窗口大小范围
• --x/--y：窗口初始位置

特殊窗口模式

• --full-screen：全屏启动
• --maximize：最大化启动
• --always-on-top：窗口置顶

标题栏样式 (--title-bar-style)

macOS 专属选项，控制标题栏外观。建议配合自定义 CSS 实现更好的视觉效果。

浏览器功能定制

用户代理 (--user-agent)

自定义浏览器标识，可用于绕过某些网站的移动版限制。

文件下载 (--file-download-options)

通过 JSON 配置下载行为，如是否显示"另存为"对话框。

全局快捷键 (--global-shortcuts)

注册系统级快捷键来触发应用内操作，配置示例：

[
  {
    "key": "Ctrl+Shift+Z",
    "inputEvents": [
      {
        "type": "keyDown",
        "keyCode": "Space"
      }
    ]
  }
]

程序化 API

除了命令行，Nativefier 还提供 JavaScript API 供开发者集成：

const nativefier = require('nativefier').default;

const options = {
  name: 'MyApp',
  targetUrl: 'http://example.com',
  platform: 'windows',
  arch: 'x64'
};

nativefier(options, (error, appPath) => {
  if (error) {
    console.error(error);
    return;
  }
  console.log('App created at:', appPath);
});

高级功能

访问 Electron Session

通过注入脚本可以与 Electron 的底层会话交互，实现更深入的控制：

// 在主进程中
win.webContents.executeJavaScript(`
  window.electronSession = require('electron').session;
`);

安全注意事项

1. 使用 --insecure 选项会降低安全性，仅在开发时使用
2. 便携模式应用包含用户数据，分享需谨慎
3. 考虑使用 --disable-dev-tools 防止用户访问开发者工具

常见问题解决方案

1. M1 Mac 构建问题：明确指定 --arch arm64
2. Widevine DRM 支持：需要特殊签名处理
3. Linux 应用名称：避免使用空格

最佳实践

1. 为生产环境应用添加合适的图标和元数据
2. 使用 --title-bar-style 配合自定义 CSS 实现原生体验
3. 通过 --process-envs 注入必要的环境变量
4. 考虑使用 --single-instance 防止应用多开

结语

Nativefier 提供了丰富的选项来定制网页打包应用的行为和外观。通过合理组合这些选项，开发者可以创建出既美观又功能完善的桌面应用。无论是简单的快速打包还是复杂的定制需求，Nativefier 都能提供相应的解决方案。

nativefier Make any web page a desktop application 项目地址: https://gitcode.com/gh_mirrors/na/nativefier