PageFlow：在无限画布上跑真实页面，把路由、接口、测试和诊断放进同一个上下文

PageFlow 是一个开发环境页面流程可视化插件。它读取项目路由，在无限画布上运行真实页面，把页面之间的导航关系、接口请求、相关测试和诊断结果收拢到同一个上下文里。

• 仓库：fitoe/unplugin-pageflow
• 在线文档：pageflowjs.github.io
• npm：unplugin-pageflow

除了 Vite 插件，它还有一个独立的 Chrome 扩展：不改目标项目就能用页面、接口、基础诊断、截图和 Todo。需要源码、HMR 和测试集成时用 unplugin。

解决什么问题

应用变大之后，页面信息散落在路由、模块、接口和测试里。日常要回答的问题往往是：项目到底有哪些页面？这个按钮会跳到哪里？某页面从哪里进来、又能去哪？当前页面调了哪些接口？有没有关联测试和明显问题？

流程图要额外维护，静态截图容易过期。PageFlow 直接用项目正在运行的页面和路由，把答案放回一张可拖动、可缩放、可探索的画布。

工作方式分三步：

1. 从框架路由或显式配置发现页面。
2. 页面按路由层级组织，进入视口时按需渲染，不会预先启动整个应用的所有 iframe。
3. 聚焦页面后识别链接与程序式导航，把关联页面移到焦点页周围，从实际交互位置连线；右侧面板集中显示接口、测试和诊断结果。

核心能力

快速开始

pnpm add -D unplugin-pageflow
# 也可 npm install -D unplugin-pageflow

// vite.config.ts
import PageFlow from 'unplugin-pageflow'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    PageFlow.vite(),
  ],
})

启动项目 pnpm dev，打开：

http://localhost:5173/__unplugin-pageflow/

宿主页面右下角会出现浮动按钮，点击后在新窗口打开面板。不需要可以关掉：

PageFlow.vite({ launcher: false })

可以在 .pageflow 里把页面绑定到 Figma 节点：

{
  "pages": {
    "/pages/agri-condition/home/index": {
      "figma": "FILE_KEY#123:456"
    }
  }
}

未绑定时，直接点常驻 Figma 按钮，粘贴含节点链接的任意文本，会自动识别并保存 fileKey#nodeId。想检查绑定设计文件是否有新版本，可在运行 PageFlow 的本地环境设置 FIGMA_ACCESS_TOKEN（也兼容 FIGMA_TOKEN）。令牌是当前环境的全局能力，不属于项目配置，只在本地服务端使用。

浮动按钮只注入开发环境，不进入生产构建；端口跟随项目的 Vite 开发服务器。Vue Router 路由会自动发现；uni-app 以 pages.json 作为页面集合与顺序的唯一来源，.pageflow 中的 routes 只用于覆盖路由元数据或补充自定义页面。

框架支持

开发环境专用与边界

• 仅在开发服务器中启用，不向生产构建注入 runtime。
• 页面只在进入视口或参与聚焦时才挂载真实预览。
• 只分析焦点页的一层导航关系，不持续扫描整个应用。
• 缩略图、测试结果和画布状态使用本地有界缓存。
• 项目专属规则通过可选 Inspector 注册，不进入核心。

页面诊断

可以检查这几类问题：

• 可访问性：缺少可访问名称、无效链接、交互控件嵌套。
• 布局与样式：点击区域、字号、对比度、横向溢出、图片尺寸。
• 交互与导航：纯跳转事件、重复导航、失效路由、导航方法不匹配。
• 请求：HTTP 失败、慢请求、大响应、短时间重复请求。

诊断只报告问题，不自动修改源码。Lighthouse 审计按需运行。

与 AI 协作

聚焦页面后，可以在“诊断”面板复制 AI 修复提示词，内容包含当前路由、诊断、接口请求、相关测试、页面链接和 Lighthouse 结果，可直接交给 Codex、Claude Code、Cursor 等。PageFlow 不内置模型、不上传项目数据，也不自动修改源码；编码助手改完后，Vite HMR 会让 PageFlow 自动重新检查。

当前焦点页的上下文也会同步到本地开发服务器内存的 JSON 接口：

http://localhost:5173/__unplugin-pageflow/api/ai-context?path=/pages/mine

端口和路由参数按实际项目调整；页面未聚焦时返回 404。

按需扩展 Inspector

import { registerPageFlowInspector } from 'unplugin-pageflow/inspectors'

const dispose = registerPageFlowInspector({
  id: 'project-rules',
  inspect({ document }) {
    return document.querySelector('[data-project-warning]')
      ? [{
          ruleId: 'project-warning',
          severity: 'suggestion',
          category: 'interaction',
          title: '发现项目提示',
          description: '这是由宿主项目提供的检查结果。',
        }]
      : []
  },
})

Inspector 只在请求诊断时运行，支持同步、异步和注销；单个失败不会中断其他检查。

几个常见问题

会进生产包吗？ 不会，只在开发服务器启用。

会替代 Storybook / 测试框架 / 设计工具吗？ 不会。它把路由和真实页面组织成可探索画布，并关联已有的接口、测试和诊断。

会自动点击页面或提交表单吗？ 不会自动操作业务控件，也不绕过认证或授权。需要注意预览页面仍可能执行自身的初始化逻辑，涉及真实写入时应使用本地或可清理的测试环境。

动态路由和登录页面能预览吗？ 可以通过配置提供安全的动态参数和本地预览会话。它不接管权限模型，也不要在页面状态里注册 Token、密码或验证码。

开发要求 Node.js >= 20.19、npm >= 10。日常检查用 pnpm check，发布前完整检查用 pnpm check:full。