如何在 Vite 项目中使用 index.php 作为入口文件

Vite 默认仅支持 index.html 作为 HTML 入口，但通过 vite-plugin-php 插件，可无缝将 index.php 设为入口，无需修改构建逻辑或手动处理 PHP 渲染。

Vite 默认仅支持 index.html 作为 HTML 入口，但通过 vite-plugin-php 插件，可无缝将 index.php 设为入口，无需修改构建逻辑或手动处理 PHP 渲染。

Vite 从一开始就是按现代前端构建的思路来设计的，所以默认只会把 index.html 识别为 HTML 入口文件。可一旦项目是从 Create React App 迁到 Vite，情况往往没这么简单：如果原来的工程依赖的是 index.php，比如要处理服务端配置、注入环境变量、做用户身份验证，或者动态生成 meta 标签，那就不能想当然地直接换成 index.html，很多时候这条路根本走不通。

幸运的是，社区已提供成熟解决方案：vite-plugin-php。该插件在开发服务器和构建流程中透明地支持 .php 入口文件，保留 PHP 的服务端执行能力，同时兼容 Vite 的 HMR、ESM 模块解析与构建优化。

✅ 快速接入步骤如下：

1. 安装插件：

   npm install vite-plugin-php --sa ve-dev
   # 或 yarn add vite-plugin-php --dev

2. 在 vite.config.ts（或 .js）中启用：

   import { defineConfig } from 'vite';
   import react from '@vitejs/plugin-react';
   import php from 'vite-plugin-php';

export default defineConfig({ plugins: [ react(), php({ // 这里可以按需指定 PHP 入口文件路径，默认是 './index.php' entryPoint: './index.php', // 这一项也是可选的：是否在 dev server 里开启 PHP 解析，前提是本地已经装好了 PHP CLI enable: true, }) ], });

3. 确保项目根目录下存在 `index.php`，内容示例：
```php

⚠️ 注意事项：

• 开发阶段需确保系统已安装 PHP CLI（php -v 可执行），插件依赖其解析 PHP 代码；
• 构建产物仍为静态文件（HTML/JS/CSS），index.php 仅在开发时被解析；生产部署时，需由真实 PHP Web 服务器（如 Apache/Nginx + PHP-FPM）托管 index.php，Vite 构建输出的 dist/ 目录应作为 Web 根目录；
• 不建议在 index.php 中执行耗时逻辑（如数据库查询），以免影响首屏加载性能；
• 若使用 TypeScript，插件本身不校验 PHP 类型，PHP 部分请自行保障健壮性。

? 总结：vite-plugin-php 提供了轻量、标准、无侵入的集成方式，让 Vite 项目既能享受现代前端开发体验，又不牺牲 PHP 所带来的服务端灵活性——真正实现「前端现代化」与「后端可控性」的协同演进。