agent-publish-server 1.0.26 → 1.0.27

package/README.md

@@ -92,6 +92,7 @@ interface AgentConfig {
   port?: number; // 服务器端口（默认：8080）
   dir?: string; // 静态文件目录（默认："./"）
   redirect?: string; // 根路径重定向，如 "/app" 表示访问 / 时重定向到 /app
+  fallbackRedirect?: string; // 404兜底重定向，当路由匹配不上时重定向到指定路径
   log?: boolean; // 启用访问日志（默认：true）
   proxy?: {
     // API代理配置
@@ -134,6 +135,30 @@ interface AgentConfig {
 
 这样配置后，访问 `http://localhost:3000/` 会自动重定向到 `http://localhost:3000/app`。
 
+### 404兜底重定向
+
+通过 `fallbackRedirect` 配置实现当路由匹配不上时自动重定向到指定路径，避免出现黑屏或404页面：
+
+```json
+{
+  "port": 3000,
+  "redirect": "/app",
+  "fallbackRedirect": "/app",
+  "staticProxy": {
+    "/app": {
+      "target": "./dist",
+      "type": "static"
+    }
+  }
+}
+```
+
+这样配置后：
+
+- 访问 `http://localhost:3000/` 会自动重定向到 `/app`
+- 访问不存在的路由（如 `/unknown`）也会重定向到 `/app`
+- 已配置的 `staticProxy` 路径仍正常访问，不受影响
+
 ### 静态网页代理
 
 除了 API 代理外，还支持静态网页代理功能，用于代理整个网站或应用。
@@ -248,6 +273,7 @@ agent-publish-server --log false
 
 ### 版本历史
 
+- **v1.0.27**: 新增404兜底重定向配置（fallbackRedirect），当路由匹配不上时自动重定向到指定路径，避免黑屏或404错误
 - **v1.0.26**: 新增根路径重定向配置（redirect），支持访问 / 时自动跳转到指定路径
 - **v1.0.25**: 修复 staticProxy static 类型不支持 SPA History 路由刷新的问题，添加自动 fallback 到 index.html 支持
 - **v1.0.24**: 修复移动端兼容性问题，优化 HTTP 响应头设置，确保 iOS 和 Android 显示一致性

package/dist/server.js

@@ -155,7 +155,7 @@ function createServer(config) {
         next();
     });
     // 添加SPA应用的回退路由处理
-    // 只有当实际文件不存在时才回退到index.html
+    // 只有当实际文件不存在时才回退到index.html或执行fallbackRedirect
     app.use((req, res, next) => {
         // 排除API和已处理的代理请求
         if (req.path.startsWith("/api/")) {
@@ -182,8 +182,20 @@ function createServer(config) {
         if (fs_1.default.existsSync(filePath) && fs_1.default.statSync(filePath).isFile()) {
             return res.sendFile(filePath);
         }
-        // 如果路径不存在，回退到index.html
-        res.sendFile(path_1.default.join(process.cwd(), staticDir, "index.html"));
+        // 如果配置了fallbackRedirect，则重定向到指定路径
+        if (config.fallbackRedirect) {
+            const redirectPath = config.fallbackRedirect.startsWith("/")
+                ? config.fallbackRedirect
+                : `/${config.fallbackRedirect}`;
+            return res.redirect(302, redirectPath);
+        }
+        // 如果路径不存在且未配置fallbackRedirect，回退到index.html
+        const rootIndexPath = path_1.default.join(process.cwd(), staticDir, "index.html");
+        if (fs_1.default.existsSync(rootIndexPath)) {
+            return res.sendFile(rootIndexPath);
+        }
+        // 如果index.html也不存在，返回404
+        res.status(404).send("404 Not Found");
     });
     return app;
 }

package/dist/types.d.ts

@@ -12,6 +12,7 @@ export interface AgentConfig {
     port?: number;
     dir?: string;
     redirect?: string;
+    fallbackRedirect?: string;
     proxy?: Record<string, ProxyConfig>;
     staticProxy?: Record<string, StaticProxyConfig>;
     log?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-publish-server",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "A powerful frontend development server with API proxy, static file serving, and dual-mode static proxy support. Built with Node.js + Express + http-proxy-middleware. 基于 Node.js + Express + http-proxy-middleware 的强大前端开发服务器，支持API代理、静态文件服务和双模式静态代理。",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/test-fallback-redirect.json

@@ -0,0 +1,18 @@
+{
+  "port": 8080,
+  "dir": "./",
+  "redirect": "/sub_page",
+  "fallbackRedirect": "/sub_page",
+  "staticProxy": {
+    "/sub_page": {
+      "target": "./dist",
+      "type": "static"
+    },
+    "/app": {
+      "target": "http://localhost:3000",
+      "type": "http",
+      "changeOrigin": true
+    }
+  },
+  "log": true
+}