问题：umi build生成的文件如何在本地打开预览？

Question

问题：使用 Umi 框架执行 `umi build` 后生成的静态文件如何在本地直接打开预览？为何通过 `file://` 协议打开时页面空白或资源加载失败？常见原因包括路径引用错误、路由模式不兼容及静态资源未正确加载。如何配置 Umi 项目以支持本地文件系统预览？是否需修改 webpack 配置或使用特定打包插件？开发者常希望通过双击 HTML 文件快速查看构建结果，但因 Umi 默认采用 history 路由和相对路径而造成访问异常。应如何调整配置，确保构建输出适配本地文件浏览环境？

Answer 1

一、问题背景与现象描述

在使用 Umi 框架进行前端开发时，开发者通常会通过执行 umi build 命令将项目打包为静态资源文件。然而，在构建完成后尝试通过本地文件系统（即 file:// 协议）直接打开生成的 index.html 文件时，常常会出现页面空白或资源加载失败的问题。

常见表现形式包括：

• 页面完全空白，无任何错误提示
• 控制台显示资源路径 404 错误（如 JS/CSS 文件未找到）
• 路由跳转异常，首页可访问但子路由无法展示

二、问题根源分析

出现上述问题的根本原因在于：Umi 默认采用的是 HTML5 History 路由模式和相对路径策略，这在部署到 Web 服务器时没有问题，但在本地文件系统中打开时则会因协议限制导致路径解析失败。

关键问题点如下：

问题类型	说明
路径引用错误	构建后的资源路径默认为相对路径，可能导致找不到资源文件
History 路由不兼容	使用 history 模式时，需要服务端配置支持，否则子路由无法正常加载
静态资源未正确加载	由于浏览器安全策略限制，file:// 下部分异步加载行为被阻止

三、解决方案详解

要解决该问题，需从多个维度调整配置，确保构建输出适配本地文件浏览环境。

1. 修改路由模式为 hash 模式

Umi 支持 hash 和 history 两种路由模式。为了兼容本地文件系统预览，建议修改为 hash 模式：

// .umirc.ts 或 config/config.ts
export default {
  routes: [
    { path: '/', component: '@/pages/index' },
    // 其他路由...
  ],
  history: { type: 'hash' }, // 将 history 类型改为 hash
};
  

2. 配置 publicPath 为相对路径

设置 webpack 的 publicPath 为相对路径（'./'），避免资源路径错误：

export default {
  define: {
    __APP_ENV__: process.env.NODE_ENV,
  },
  publicPath: './', // 设置相对路径
};

3. 使用 umi-plugin-preview 插件（可选）

社区提供了一个专门用于支持本地预览的插件：umi-plugin-preview，可自动处理路径及路由兼容性问题：

yarn add umi-plugin-preview --dev

// .umirc.ts
export default {
  plugins: ['umi-plugin-preview'],
};

4. 启动本地静态服务器替代 file:// 方式

更推荐的方式是使用一个本地静态服务器来模拟生产环境访问方式，例如：

npx serve dist

这样可以规避浏览器对 file:// 协议的限制，同时更贴近真实部署环境。

四、流程图展示完整解决方案逻辑

graph TD
    A[执行 umi build 构建] --> B{是否使用 history 路由?}
    B -->|是| C[修改路由模式为 hash]
    B -->|否| D[继续下一步]
    D --> E{是否配置 publicPath?}
    E -->|否| F[设置 publicPath 为 ./]
    E -->|是| G[继续下一步]
    G --> H{是否需本地预览?}
    H -->|是| I[使用 umi-plugin-preview 或启动本地服务器]
    H -->|否| J[完成构建]

五、总结与拓展思考

通过对 Umi 构建配置的合理调整，可以有效解决构建后静态资源在本地文件系统下无法预览的问题。核心在于理解浏览器加载机制、路径解析规则以及路由模式差异。

对于有持续集成/部署需求的团队，建议结合自动化测试和部署工具（如 GitHub Actions、Jenkins 等）进一步优化构建流程。