NativePHP桌面版篇〡新手必学入门实践指南
概述
NativePHP 是一种通过将 PHP 代码编译成原生二进制代码，使开发者能够使用 PHP 语言来构建原生应用程序。与传统的 PHP 脚本不同，NativePHP 应用程序可以直接在操作系统的本机环境中运行，无需依赖 Web 服务器或解释器。2025.4.13 NativePHP桌面版V1.0正式发布。
环境要求
- PHP 8.3+
- Laravel 11或者更高
- Node 22+
- Windows 10+ / macOS 12+ / Linux
NativePHP 的最佳开发体验是直接在开发计算机上运行 PHP 和 Node。
“请注意，虽然可以从虚拟化环境或容器开发和运行应用程序，但您可能会遇到更多意外问题，并且需要更多手动步骤来创建工作版本。
示例项目
克隆示例代码
官方仓库：https://github.com/NativePHP/kitchen-sink
git clone git@github.com:NativePHP/kitchen-sink.git安装后端依赖
通过composer工具安装依赖
composer install出现以下界面表示安装成功，否则请自行根据错误提示解决环境和依赖包冲突问题
> Illuminate\Foundation\ComposerScripts::postAutoloadDump
>@phpartisanpackage:discover--ansi
INFODiscoveringpackages.
laravel/dusk.......................................DONE
laravel/tinker.....................................DONE
livewire/livewire.....................................DONE
nativephp/electron.....................................DONE
nativephp/laravel.....................................DONE
nesbot/carbon.....................................DONE
nunomaduro/collision.....................................DONE
nunomaduro/termwind.....................................DONE安装前端依赖
npm i
启动开发模式
composer native:dev请确保命令全部执行完成出现以下界面
> Composer\Config::disableProcessTimeout
> npx concurrently -c "#93c5fd,#fb7185" -k "php artisan native:serve --no-interaction""npm run dev" --names=app,vite
[vite]
[vite] > dev
[vite] > vite
[vite]
[vite]
[vite] VITE v6.2.5 ready in563 ms
[vite]
[vite] ➜ Local: http://localhost:5173/
[vite] ➜ Network: use --host to expose
[app]
[app] Starting NativePHP dev server...
[app]
[app] Fetching latest dependencies...
[app]
[app] Installing NPM dependencies (This may take a while)...
[app]
[app] Installing NPM dependencies using the npm package manager...
[app]
[app] Fetching latest dependencies...
[app]
[vite]
[vite] LARAVEL v12.8.1 plugin v1.2.0
[vite]
[vite] ➜ APP_URL: http://kitchen-sink.test
[app]
[app] Starting NativePHP app
[app]
[app] Copying latest CA Certificate...
[app]
[app] Running the dev script with npm...
[app]
[app] Fetching latest dependencies...
[app]
就是这样！您现在应该看到您的 Laravel 应用程序在本机桌面窗口中运行。 🎉
或者实现一个自己的登录界面
构建发布
php artisan native:build
构建成功的话，会在目录下生产一个dist文件夹，双击exe文件，即可运行桌面应用
自定安装
安装NativePHP
composer require nativephp/electron
或者指定PHP版本
$ /usr/local/php-8.3.20/bin/php /home/build/composer.phar require nativephp/electron
安装依赖
php artisan native:install
运行开发模式
php artisan native:serve
常见错误
Q1：MissingAppKey 错误
提示错误Laravel ：Illuminate\Encryption\MissingAppKeyException No application encryption key has been specifi
如果你还没有设置 APP_KEY，你可以通过以下命令来生成一个：
php artisan key:generate
确保你的 .env 文件中包含了正确的 APP_KEY。你可以这样查看或确认它：
APP_KEY=base64:你的密钥字符串
Q2：前端启动异常
启动报错vite handling the native:dev event returned with error code 1
--> Sending SIGTERM to other processes..
Script npx concurrently -c "#93c5fd,#fb7185"
-k "php artisan native:serve --no-interaction"
"npm run dev" --names=app,vite handling the native:dev event returned with error code 1
请确保你已经安装了前端依赖，即执行npm i命令
Q3：服务启动异常
错误提示package.json has a "packageManager" field
$ npm i
This project is configured to use yarn because
\vendor\nativephp\electron\resources\js\package.json has a "packageManager" field
这个错误提示是由于package.json依赖包已经有这个文件了，删除"packageManager": "npm@11.3.0+sha512.96eb611483f49c55f7fa74df61b588de9e213f80a256728e6798ddc67176c7b07e4a1cfc7de8922422cbce02543714367037536955221fa451b0c4fefaf20c66" 这个配置即可，删除后再通过命令npm i重新安装依赖
腾讯云开发者
