在 NixOS 上运行 Laravel 11 需显式声明 PHP 扩展、硬编码时区、禁用 artisan serve，改用 Nginx+PHP-FPM 或 php -S + router.php，并修正 storage 权限与 FPM 用户配置。
在 NixOS 上运行 Laravel 11 不是“装完 PHP 就行”的事——Nix 的声明式包管理、无全局依赖、隔离的 PHP 环境，会让默认的 Laravel 启动流程直接失败。必须绕过 php artisan serve 的隐式假设，显式声明所有运行时依赖（包括扩展、时区、storage 权限），并用 Nix 方式接管 Web 服务。
PHP 8.2+ 及扩展不能靠 phpPackages 默认值凑合
NixOS 的 php82 包本身不启用任何扩展；Laravel 11 启动前就校验 mbstring、openssl、pdo、tokenizer、xml、curl、json，缺一个就报 Class not found 或直接退出。
- 必须用
withExtensions显式启用：php82.withExtensions (ps: with ps; [ mbstring openssl pdo tokenizer xml curl json ]) -
date.timezone必须在php.ini中硬编码（Nix 不走系统/etc/php.ini）：在phpPackage配置里加extraConfig = "date.timezone = \"Asia/Shanghai\""; - 别信
php -m | grep mbstring输出——它可能来自另一个 PHP 实例；确认方式是：在项目目录下执行$(php82.withExtensions(...))/bin/php -m | grep mbstring
composer create-project 必须指定 --no-interaction 且跳过 laravel/installer
NixOS 没有 TTY，laravel/installer 的交互式提示会卡死，而且它的默认行为会生成无效的 .env（APP_KEY 是占位符）。Laravel 11 官方已弃用该工具。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 正确命令：
composer create-project laravel/laravel:^11.0 myapp --no-interaction --prefer-dist - 执行前确保 Composer 用的是 3.x：
composer --version输出必须是3.x；NixOS 用户应从phpPackages.composer_3获取，而非系统默认的composer - 进项目后立刻运行：
$(php82.withExtensions(...))/bin/php artisan key:generate—— 用你声明的那个 PHP 实例，不是php命令
别用 php artisan serve，它在 NixOS 上根本跑不起来
artisan serve 依赖内置 PHP 服务器 + 动态加载 public/index.php，但 Nix 的 php82 编译时禁用了 --enable-cli-server（安全策略），运行直接报 Server API is not supported。
- 替代方案只有两个：
① 用 Nginx + PHP-FPM（推荐，最接近生产）
② 用
php -S手动启动（仅开发，需自己写路由回调文件） - 若选 Nginx：
- 把
root指向myapp/public-fastcgi_pass指向unix:/run/php-fpm/myapp.sock（需在services.phpfpm.pools里配好该 pool） - 关键：fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;—— NixOS 默认没设$realpath_root，漏了就 404 - 若选
php -S： 写一个router.php，内容为：if (file_exists(__DIR__.'/public/'. $_SERVER['REQUEST_URI'])) { return false; } else { include __DIR__.'/public/index.php'; }然后运行：$(php82.withExtensions(...))/bin/php -S localhost:8000 router.php
storage 和 bootstrap/cache 目录权限是静默失败点
NixOS 的构建环境默认只读，且用户主目录（~）可能被 home-manager 管理，导致 php artisan cache:clear 或日志写入失败，错误不报在终端，只出现在 storage/logs/laravel.log 里（如果它能创建的话）。
- 手动修复：
chmod -R 775 storage bootstrap/cachechown -R $(whoami):$(whoami) storage bootstrap/cache - 更 Nix 的做法：在
home.nix或configuration.nix里用system.activationScripts加一段：chmod -R u+rwX,g+rwX storage bootstrap/cache || true - 注意：NixOS 的
tmpfs或stateVersion升级可能清空storage，建议把storage/logs软链到/var/log/myapp（用systemd.tmpfiles创建）
最常被忽略的是：NixOS 的 PHP-FPM pool 默认以 nobody 用户运行，而你的项目在 ~/code/myapp，nobody 根本没权限读取；必须显式设 user = "yourusername" 和 group = "yourusername"，否则 Nginx 返回 502 且日志里只有一行 connect() to unix:/run/php-fpm/myapp.sock failed。
