沃德开源文档

Appearance

快速上手 ​

本指南将帮助您快速在本地运行本项目，包含服务端（Server）、管理后台（Admin）和Web展示前端（Web）。 开发环境下，您无需配置 Nginx、Apache 这类复杂的 Web 服务器即可快速看到效果并参与二次开发。

🔧 前序准备与环境要求 ​

请确保本地开发机器上安装了以下必备环境：

  • PHP >= 8.0.0 (推荐使用 8.0)
  • Composer (PHP的包/依赖管理工具)
  • Node.js >= 18.0.0 (支持更新特性的前端构建)
  • npm (Node自带的包管理工具)

💡 温馨提示：建议将 php 和 node 路径添加至系统的环境变量，以确保在终端能直接使用 php -v 和 node -v。

💻 技术栈 ​

本项目是一个现代化的前后端分离架构，主要应用栈如下：

  • 服务端：采用 ThinkPHP 8.0 作为核心框架。
  • 管理后台 (PC前端)：采用 Vue 3 + Vite + Element Plus + TypeScript 构建。
  • Web前端 (SSR客户端)：采用 Nuxt 4 构建服务端渲染 Web，结合 TailwindCSS 进行样式排版。

📂 目录结构概述 ​

text
wdadmin-php/
├─📂 server //服务端根目录（管理后台、接口）
│  ├─📂 application //应用目录
│  │  ├─📂 adminapi //管理后台
│  ├─📂 public //WEB目录（对外访问目录）
│  │  ├─📄 index.php //php入口文件
│  │  ├─📂 admin //已编译的后台前端代码入口（上线运行）
│  │  ├─📂 install //安装程序目录
│  ├─📄 .env //项目环境配置文件（自动写入了数据库等信息）
├─📂 admin //管理后台前端源码
├─📂 web //PC端前台源码 (Nuxt)
├─📄 LICENSE //开源许可证说明
└─📄 README.md //简述向导

🚀 一、启动服务端 (Server) ​

服务端提供对数据库的操作和所有的业务 API 接口。

  1. 进入服务端目录 在终端中使用命令进入 server 文件夹：

    bash
    cd server

  2. 安装服务端依赖 使用 Composer 工具安装项目中的各类 PHP 扩展与依赖包：

    bash
    # 如果找不到命令，可检查是否全局配置 composer 环境变量
composer install

  3. 确认环境变量（已自动生成）

    • 项目通过一键安装成功后，数据库等相关配置信息已自动写入到 server 目录下的 .env 文件中，不再提供 .env.example 文件。
    • 如果后续需要变更数据库连接凭证等信息，您可以直接打开并修改 .env 文件。

  4. 启动内置服务 ThinkPHP 提供了一个非常方便的开发环境内建命令：

    bash
    php think run

    启动成功后输出形如：ThinkPHP Development server is started On <http://127.0.0.1:8000/>，代表服务端成功运行。

🛠️ 二、启动管理后台 (Admin) ​

管理后台为独立开发编译的前端端点。

  1. 进入管理后台目录 保留服务端的终端运行，在此处新开一个命令行终端：

    bash
    cd admin

  2. 设置后端接口域名

    • 复制项目里的环境变量配置示例 .env.development.example 并重命名为 .env.development。
    • 将文件内声明的 VITE_APP_BASE_URL 指向您刚刚在第一步启动的后端服务地址（通常为：http://127.0.0.1:8000）。

  3. 安装前端依赖 建议提前设置 npm 淘宝镜像源以提升下载速度。

    bash
    npm config set registry https://registry.npmmirror.com
npm install

  4. 开发模式运行 依靠 Vite 快速冷启动项目：

    bash
    npm run dev

    运行成功后，访问终端上的本地地址（例如 http://localhost:5173），即可本地预览和修改管理后台的功能。

🌐 三、启动 Web C端 (Web) ​

Web使用 Nuxt 框架，自带服务端能力。如果您的工作不涉及向普通用户展现的 Web 端，可跳过此步骤。

  1. 进入 Web 端目录 新开一个终端实例，切换进入 web 文件夹：

    bash
    cd web

  2. 安装依赖

    bash
    npm install

  3. 开发环境下启动 Nuxt 服务

    bash
    npm run dev

    服务启动完毕后，终端将会打印监听的端口及地址（通常为：http://localhost:3000），在浏览器中打开即可实时查看您的 Web 端页面。

⚠️ 注意事项与常见问题 ​

  1. 服务停止 不论在使用的是 php think run 还是 npm run dev 的终端中，同时按下 Ctrl + C（或在 Mac 用 Command + .）即可终止对应的本地服务。

  2. 端口冲突 如果命令提示「端口已被占用」，可能是由您电脑上其他程序引起的。请更改启动时的指定端口，或者排查退出相应的后台进程。

  3. 关于生产环境线上发布 在本地开发模式下使用上述指令即足够高效。但在把站点应用到正式生产服务器上时，禁止使用 php think run 持续作为 web 服务器。您需要将前端项目打包（使用 npm run build），并搭配专业的 Nginx、Apache、PM2（部分SSR） 等成熟的 Server 基础环境部署站点。