umi配置文件详解：.umirc.js完全指南

umi配置文件详解：.umirc.js完全指南

【免费下载链接】umi A framework in react community ✨ 项目地址: https://gitcode.com/gh_mirrors/umi8/umi

在使用Umi框架（React社区的一款框架）开发项目时，配置文件是项目的核心。.umirc.js作为Umi的主要配置文件，掌握它的配置选项能帮助开发者更灵活地定制项目构建和运行行为。本文将详细介绍.umirc.js的各类配置选项，结合实际代码示例和项目文档，让你全面了解如何通过配置优化项目开发流程。

配置文件基础

Umi的配置文件支持两种格式：.umirc.js或config/config.js。它们的作用相同，选择其中一种即可。配置文件采用CommonJS或ES Module规范导出一个对象，包含项目所需的各项配置。

官方文档中对配置有详细说明，你可以通过docs/config/README.md查看完整配置列表。

基本配置

plugins（插件配置）

plugins配置用于指定项目使用的Umi插件，类型为数组。插件是Umi功能扩展的主要方式，比如集成Dva、路由管理等。

export default {
  plugins: [
    'umi-plugin-dva', // 集成Dva状态管理
    ['umi-plugin-routes', {  // 带参数的插件配置
      update(routes) { 
        // 自定义路由处理逻辑
        return routes;
      },
    }],
  ],
};

Umi项目中常见的插件如umi-plugin-dva（packages/umi-plugin-dva/），用于集成Dva数据流方案，在配置中添加该插件即可启用相关功能。

hd（高清方案）

设置为true时，Umi会开启高清方案，适配不同屏幕分辨率。默认值为false。

export default {
  hd: true, // 启用高清方案
};

hashHistory（路由模式）

控制路由使用的History模式。设为true时使用hash模式（URL中带#），默认使用browser history模式。

export default {
  hashHistory: true, // 使用hash路由模式
};

构建流程配置

outputPath（输出路径）

指定项目构建后的输出目录，默认值为'./dist'。可以根据项目部署需求修改输出路径。

export default {
  outputPath: './build', // 构建产物输出到build目录
};

exportStatic（静态导出）

设为true或对象时，Umi会将所有路由导出为静态HTML文件，有利于SEO和静态站点部署。默认只输出一个index.html。

export default {
  exportStatic: { 
    htmlSuffix: true // 为静态页面添加.html后缀
  },
};

更多静态导出配置可参考docs/guide/deploy.md中的部署说明。

disableHash（文件名哈希）

默认情况下，Umi构建后的文件名会包含哈希值，用于避免浏览器缓存问题。设置disableHash为true可移除文件名中的哈希。

export default {
  disableHash: true, // 构建文件名不带哈希
};

Webpack相关配置

theme（主题配置）

用于自定义项目主题，实际上是配置Less变量。支持对象或指向配置文件的字符串路径。

export default {
  theme: {
    '@primary-color': '#1DA57A', // 自定义主题主色
    '@link-color': '#1890ff',    // 链接颜色
  },
};

如果主题配置复杂，可将其提取到单独文件，如：

export default {
  theme: './theme-config.js', // 从外部文件导入主题配置
};

proxy（代理配置）

配置开发环境下的API代理，解决跨域问题。通过webpack-dev-server的proxy实现。

export default {
  proxy: {
    '/api': {
      target: 'http://jsonplaceholder.typicode.com/', // 目标API地址
      changeOrigin: true, // 开启跨域
      pathRewrite: { '^/api': '' }, // 重写路径，去掉/api前缀
    },
  },
};

配置后，访问/api/users会代理到http://jsonplaceholder.typicode.com/users。详细的代理配置可参考docs/config/README.md中的proxy部分。

define（全局变量）

通过webpack的DefinePlugin向代码注入全局变量，值会自动进行JSON.stringify处理。

export default {
  define: {
    'process.env.NODE_ENV': process.env.NODE_ENV, // 注入环境变量
    'APP_VERSION': '1.0.0', // 注入应用版本号
  },
};

高级配置

env（环境特定配置）

针对不同环境（development/production）进行差异化配置。开发环境的环境变量是'development'，构建时是'production'。

export default {
  extraBabelPlugins: ['transform-runtime'],
  env: {
    development: {
      extraBabelPlugins: ['dva-hmr'], // 开发环境启用HMR插件
    },
  },
};

上述配置中，开发环境下extraBabelPlugins会合并基础配置和环境配置，变为['transform-runtime', 'dva-hmr']。

externals（外部依赖）

配置webpack的externals属性，将某些依赖排除在构建产物之外，通过外部引入（如CDN）。

export default {
  externals: {
    'react': 'window.React', // React通过外部CDN引入
    'react-dom': 'window.ReactDOM',
  },
};

使用该配置后，需在HTML模板中手动引入对应的CDN资源。Umi的HTML模板配置可参考docs/guide/html-template.md。

配置示例：完整的.umirc.js

结合上述配置选项，以下是一个完整的.umirc.js示例，涵盖开发常用配置：

export default {
  // 基本配置
  plugins: [
    'umi-plugin-dva',
    ['umi-plugin-routes', {
      update(routes) {
        // 简化路由配置示例
        return routes.filter(route => route.path !== '/test');
      },
    }],
  ],
  hd: true,
  hashHistory: process.env.NODE_ENV === 'development',

  // 构建配置
  outputPath: './dist',
  exportStatic: { htmlSuffix: true },
  disableHash: false,

  // Webpack配置
  theme: {
    '@primary-color': '#1DA57A',
  },
  proxy: {
    '/api': {
      target: 'http://localhost:3000',
      changeOrigin: true,
    },
  },
  define: {
    'APP_ENV': process.env.NODE_ENV,
  },

  // 环境特定配置
  env: {
    development: {
      devtool: 'eval-cheap-module-source-map',
    },
    production: {
      extraBabelPlugins: ['transform-remove-console'],
    },
  },
};

总结

.umirc.js是Umi项目的核心配置文件，通过本文介绍的配置选项，你可以灵活定制项目的构建流程、路由行为、外部依赖等关键环节。实际开发中，可根据项目需求结合官方文档docs/config/README.md进行配置。合理的配置能提升开发效率，优化项目性能，为后续部署和维护打下良好基础。

掌握.umirc.js的配置后，你还可以进一步探索Umi的插件开发、高级路由配置等功能，深入挖掘框架潜力。如果在配置过程中遇到问题，可参考Umi的FAQ文档docs/guide/faq.md或社区资源获取帮助。

【免费下载链接】umi A framework in react community ✨ 项目地址: https://gitcode.com/gh_mirrors/umi8/umi