@keqi.gress/plugin-dev-server

Gress 插件前端开发服务器 - 提供热更新和后端联调能力

🎯 功能特性

• ⚡️ 基于 Vite 的快速热更新 (HMR)
• 🔄 自动代理后端 API 请求
• 🎨 支持自定义 Vite 配置
• 📦 零配置启动，开箱即用
• 🔧 灵活的配置选项
• 🚀 支持多插件并行开发
• 🛣️ 完整支持 Vue Router（History/Hash 模式）
• 🤖 自动扫描 views 目录生成路由（约定优于配置）
• 🎯 Mock API 支持（模拟后端路由和菜单配置）

📦 安装

在插件前端项目中安装：

npm install @keqi.gress/plugin-dev-server --save-dev

或使用本地路径（开发阶段）：

npm install file:../../gress/gress-plugin-packages/plugin-dev-server --save-dev

🚀 快速开始

零配置模式（推荐）

只需 3 步，无需创建任何路由文件！

# 1. 创建 views 组件
mkdir -p src/views
echo '<template><div>首页</div></template>' > src/views/HomePage.vue

# 2. 创建配置文件
echo 'export default { pluginName: "my-plugin" }' > gress-dev.config.js

# 3. 启动开发服务器
npx gress-dev

访问 http://localhost:3000/ 即可看到页面！

工作原理：

• ✅ 自动扫描 src/views 目录
• ✅ 自动生成路由配置
• ✅ 自动注入应用入口（main.ts、App.vue、router）
• ✅ 自动启动开发服务器

你只需要：

• 创建 Vue 组件
• 配置插件名称

1. 创建配置文件

在插件前端根目录创建 gress-dev.config.js：

export default {
  // 插件名称（必填）
  pluginName: 'appstore',
  
  // 后端服务地址（可选，默认 http://localhost:8080）
  backendUrl: 'http://localhost:8080',
  
  // 开发服务器端口（可选，默认 3000）
  port: 3001,
  
  // API 前缀（可选，默认 /api/plugin/{pluginName}）
  apiPrefix: '/api/plugin/appstore',
  
  // 是否自动扫描 views 目录生成路由（可选，默认 true）
  autoScanRoutes: true,
  
  // 手动配置的路由（可选，会覆盖自动扫描的路由）
  devRoutes: [
    // 特殊路由可以在这里配置
    {
      path: '/custom-path',
      component: 'CustomPage',
      meta: { title: '自定义页面' }
    }
  ],
  
  // 是否启用热更新（可选，默认 true）
  hmr: true,
  
  // 是否自动打开浏览器（可选，默认 false）
  open: false,
  
  // 路由基础路径（可选，默认 '/'）
  // 用于子路径部署，如 '/plugins/appstore/'
  base: '/'
}

2. 修改 package.json

{
  "scripts": {
    "dev": "gress-dev",
    "build": "vite build"
  },
  "devDependencies": {
    "@keqi.gress/plugin-dev-server": "^1.0.0"
  }
}

3. 启动开发服务器

npm run dev

📖 配置选项

基础配置

interface GressDevConfig {
  /** 插件名称（必填） */
  pluginName: string
  
  /** 后端服务地址（可选） */
  backendUrl?: string
  
  /** 开发服务器端口（可选） */
  port?: number
  
  /** API 前缀（可选） */
  apiPrefix?: string
  
  /** 是否启用热更新（可选） */
  hmr?: boolean
  
  /** 是否自动打开浏览器（可选） */
  open?: boolean
  
  /** 额外的 Vite 配置（可选） */
  vite?: InlineConfig
  
  /** 额外的代理配置（可选） */
  proxy?: Record<string, any>
}

高级配置示例

export default {
  pluginName: 'portal',
  backendUrl: 'http://localhost:8080',
  port: 3002,
  
  // 自定义 Vite 配置
  vite: {
    resolve: {
      alias: {
        '@': '/src'
      }
    },
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "@/styles/variables.scss";`
        }
      }
    }
  },
  
  // 额外的代理配置
  proxy: {
    '/api/other': {
      target: 'http://localhost:9000',
      changeOrigin: true
    }
  }
}

🔧 命令行选项

# 使用默认配置
gress-dev

# 指定端口
gress-dev --port 3003

# 自动打开浏览器
gress-dev --open

# 指定配置文件
gress-dev --config custom-config.js

🌟 使用场景

场景 1：零配置开发（推荐）

cd gress-plugin-appstore/frontend

# 创建 views 组件
mkdir -p src/views
echo '<template><div>首页</div></template>' > src/views/HomePage.vue
echo '<template><div>列表</div></template>' > src/views/ApplicationList.vue

# 启动开发服务器（自动扫描 views 目录生成路由）
npm run dev

访问：

• http://localhost:3001/ → HomePage.vue
• http://localhost:3001/application-list → ApplicationList.vue

场景 2：自定义路由

// gress-dev.config.js
export default {
  pluginName: 'appstore',
  
  // 手动配置特殊路由
  devRoutes: [
    {
      path: '/applications',  // 自定义路径
      component: 'ApplicationList',
      meta: { title: '应用列表', icon: 'Apps' }
    },
    {
      path: '/applications/:id',
      component: 'ApplicationDetail',
      meta: { title: '应用详情' }
    }
  ]
}

场景 3：多插件并行开发

# 终端 1 - 启动 appstore 插件
cd gress-plugin-appstore/frontend
npm run dev  # 端口 3001

# 终端 2 - 启动 portal 插件
cd gress-plugin-portal/frontend
npm run dev  # 端口 3002

场景 3：联调后端 API

所有发送到 apiPrefix 的请求会自动代理到后端：

// 前端代码
const response = await fetch('/api/plugin/appstore/applications')
// 实际请求: http://localhost:8080/api/plugin/appstore/applications

场景 4：访问路由

所有前端路由都可以直接访问，支持浏览器刷新：

http://localhost:3001/                    # 首页
http://localhost:3001/applications        # 应用列表
http://localhost:3001/settings            # 设置页

详见 路由访问指南

🎨 环境变量注入

开发服务器会自动注入以下全局变量：

declare const __PLUGIN_NAME__: string      // 插件名称
declare const __API_PREFIX__: string       // API 前缀
declare const __BACKEND_URL__: string      // 后端地址

在代码中使用：

console.log('Plugin:', __PLUGIN_NAME__)
console.log('API Prefix:', __API_PREFIX__)

📝 TypeScript 支持

创建 env.d.ts 文件：

/// <reference types="vite/client" />

declare const __PLUGIN_NAME__: string
declare const __API_PREFIX__: string
declare const __BACKEND_URL__: string

🔍 调试

开发服务器会输出代理请求日志：

[Proxy] GET /api/plugin/appstore/applications -> http://localhost:8080/api/plugin/appstore/applications

📄 License

MIT

📚 相关文档

• 快速开始
• 集成指南
• 路由访问指南
• 自动路由扫描指南 ⭐ 新功能
• 开发环境路由配置
• 配置示例