⚡ 快速开始

本章覆盖从环境准备到服务启动的完整流程：安装依赖、配置 Web 服务、初始化数据库、启动前后端开发服务。

✨ 环境要求

类型	要求
PHP	>= 8.3，建议与生产环境保持一致
PHP 扩展	pdo_mysql、fileinfo、mbstring、openssl、curl、gd 等常用扩展
Composer	>= 2.2，Laravel 13 依赖 Composer Runtime API ^2.2
Node.js	后端 Admin / 跨端 uni-app 均建议 Node 22
npm / pnpm	根据各端 package.json 使用对应包管理器，建议团队统一版本
数据库	MySQL 或兼容数据库，建议 MySQL 8.x
Web 服务	Nginx，负责站点入口、静态资源、反向代理和伪静态配置
Redis	可选，建议生产环境启用，用于缓存、队列、验证码、会话或高频状态数据
开发工具	PhpStorm / VS Code、HBuilderX、微信开发者工具等

🌐 Web 服务配置（Nginx）

项目站点根目录应指向仓库下的 public 目录，而非仓库根目录。所有 HTTP 请求由 public/index.php 统一入口分发。

以下是一份适用于 SunAdmin 的 Nginx 站点配置示例：

server {
    listen 80;
    server_name your-domain.com;
    # 如需 HTTPS，可在此处配置 ssl_certificate / ssl_certificate_key

    # 站点入口目录指向 public
    root /www/wwwroot/SunAdmin/public;
    index index.php;

    # 建议的安全与性能设置
    charset utf-8;
    client_max_body_size 64m;

    # 静态资源缓存（admin / h5 / modules 等前端产物）
    location ~* \.(css|js|woff2?|ttf|eot|svg|png|jpe?g|gif|ico|webp|mp4|webm)$ {
        expires 7d;
        access_log off;
    }

    # 伪静态：将非文件、非目录请求统一转发至 index.php
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # PHP-FPM 处理
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;

        # 传递 Authorization 与 X-XSRF-Token 请求头
        fastcgi_param HTTP_AUTHORIZATION $http_authorization;
        fastcgi_param HTTP_X_XSRF_TOKEN $http_x_xsrf_token;
    }

    # 禁止访问隐藏文件（.env、.git 等）
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

配置说明：

配置项	说明
root	指向项目 public 目录，这是唯一的 Web 入口
try_files	伪静态核心：先尝试匹配静态文件，不存在则转发至 index.php，由 Laravel 路由接管
fastcgi_param HTTP_AUTHORIZATION	传递 Authorization 请求头，Sanctum Token 认证依赖此配置
fastcgi_param HTTP_X_XSRF_TOKEN	传递 X-XSRF-Token 请求头，管理端 AJAX 请求的 CSRF 校验依赖此配置
location ~ /\.(?!well-known)	阻止直接访问 .env、.git 等敏感文件

如果使用宝塔面板、1Panel 等运维工具创建站点，通常只需将网站目录设置为 public，并在伪静态规则中填入上述 location / 部分即可；Authorization 等 Header 的透传需确认 FastCGI 参数中已包含。

🛠️ 后端初始化

项目默认通过安装向导完成初始化，请在完成基础运行环境准备后，访问：

http(s)://你的域名/install

安装向导会引导你完成数据库、缓存、管理员账号、应用密钥与基础数据初始化。

如果你需要重新初始化安装项目，请先删除根目录下的 install.lock 文件，再重新访问安装向导。

初始化完成后，可通过以下地址进入后台管理端：

http(s)://你的域名/admin

可通过以下地址访问 H5 端：

http(s)://你的域名/h5

如果需要访问小程序端，请先编译对应小程序产物，并上传到对应的小程序平台后进行预览或发布访问。

🖧 后端开发服务

后端依赖安装

# 安装后端 PHP 依赖
composer install

环境配置可按实际情况调整：

.env

常用命令：

# 启动 Laravel 本地开发服务
php artisan serve

# 运行后端测试用例
php artisan test

# 创建本地存储公开访问软链接
php artisan storage:link

说明：

• 首次安装请使用安装向导，安装向导会创建后台管理员账号；单独执行 php artisan migrate / php artisan db:seed 不会完成完整初始化流程。
• php artisan migrate / php artisan db:seed 属于已安装项目的维护或开发命令，不作为首次安装推荐流程。
• 已安装项目升级时，如果当前环境被识别为生产环境，请使用 php artisan migrate --force
• 生产环境安装依赖使用 composer install --no-dev --optimize-autoloader

如果初始化后更改了项目路径，请额外执行 php artisan storage:link初始化路径映射，否则本地存储上传文件可能无法通过 /storage/... 正常访问。

🪢 Admin 管理端开发服务

# 进入管理端项目目录
cd frontend/admin

# 安装管理端依赖
npm install

# 启动管理端开发服务
npm run dev

Admin 默认开发端口在 frontend/admin/package.json 中配置为 8000。接口前缀为 adminapi，由 frontend/admin/src/config/index.ts 统一定义。

🔀 uni-app 客户端开发服务

# 进入 uni-app 项目目录
cd frontend/uniapp

# 使用指定 npm 版本安装依赖
# uni-app 项目依赖的 npm 版本有特定要求，需要通过 npx 指定版本安装
npx npm@11.13.0 install

启动开发服务：

# H5 开发服务
npm run dev:h5

# 微信小程序开发构建
npm run dev:mp-weixin

# App 开发构建
npm run dev:app

编译微信小程序前，需要在 frontend/uniapp/src/manifest.json 的 mp-weixin.appid 填写微信小程序 AppID：

{
  "mp-weixin": {
    "appid": "你的微信小程序 AppID"
  }
}

微信小程序构建完成后，用微信开发者工具导入 frontend/uniapp/dist/dev/mp-weixin 目录。

其他常用命令：

# 构建生产产物
npm run build:h5
npm run build:mp-weixin
npm run build:app

# TypeScript 类型检查
npm run typecheck

📦 生产构建

# Admin 管理端
cd frontend/admin && npm run build

# uni-app H5
cd frontend/uniapp && npm run build:h5

# uni-app 微信小程序
cd frontend/uniapp && npm run build:mp-weixin

微信小程序生产构建同样需要先确认 frontend/uniapp/src/manifest.json 中的 mp-weixin.appid 已填写。

产物发布路径：

端	产物目录	Nginx 访问路径
Admin	public/admin	/admin
H5	public/h5	/h5
微信小程序	frontend/uniapp/dist/build/mp-weixin	上传至微信平台

生产环境完整部署流程（包括 Nginx 配置、队列、定时任务等）详见 部署上线。