[TOC]

React 模板工程

本模板工程是通用工程，支持前端开发和中后台开发。

基于 create-react-app v3(简称 cra3)创建，整合了 react router 等基础组件，旨在作为基础工程以便能快速衍生其他复杂工程模板。

本文档部分内容来自官方文档create-react-app 项目地址，详情参考中文文档, 英文文档

技术特性

该工程的主要技术特性如下：

SCSS / CSS Modules 样式处理（不熟悉的同学，先学习下：）
公共 SCSS mixins 支持
基于 fetch 数据请求
支持 mobx 状态管理*
支持 Fusion Design 平台，UI 和前端协同*
支持公共主题可配置
Eslint / Stylelint / Prettier 代码检查
Markdownlint 规范详情规则
代码提交日志规范
支持装饰器 @ @babel/plugin-proposal-decorators
支持可选链运算符 ?. @babel/plugin-proposal-optional-chaining
支持空位合并运算符 ?? @babel/plugin-proposal-nullish-coalescing-operator

更多特性，赶快体验！

CRA3 升级的特性，可以参考 releases[https://github.com/facebook/create-react-app/releases/tag/v3.0.1], 英文文档，中文文档

CRA2 升级的特性，可以参考英文文档，中文文档

项目规范

文件结构

├── .vscode/          			 # vscode相关
│   └── launch.json  		  	 # 存放调试配置，如Debugger for Chrome调试配置等
├── build/          		  	 # 构建目录，构建后创建
│
├── doc/            		  	 # 文档目录，存放项目相关文档
├── node_modules/   		  	 # node依赖模块，安装组件后自动创建
├── public/         		  	 # 静态文件
│   ├── favicon.ico 		  	 # H5 icon，浏览器地址栏图标
│   ├── ie.html  		       	 # ie及低版本浏览器兼容提示
│   ├── index.html  		  	 # 应用入口页模板，如果要引入第三方JS可以放在这个目录*
│   ├── logo*.png  		     	 # Web App应用图标，默认包括1x和3x两种尺寸
│   ├── manifest.json		  	 # Web App配置文件
│   └── robots.txt		    	 # robots协议配置文件
│
├── src/             		  	 # 项目root
│   ├── mock/           		 # mock目录，根据项目需要创建
│   ├── api/         		  	 # 项目api相关
│   	├── Agent.js    	  	 # 接口请求处理逻辑，默认采用fetch
│   	├── ApiUrl.js   	  	 # 接口请求api地址注册
│   	├── ResponseCode.js	     # 错误码定义
│   	└── index.js      		 # 接口的统一export
│
│   ├── assets/      		  	 # 公共静态资源（组件除外），如图片/字体/json等，文件名一律小写
│   	├── font/      		  	 # 公共字体
│   	├── img/      		  	 # 公共图片，应当按模块分文件夹存放
│   	└── index.js    	  	 # 公共资源的统一export
│
│   ├── components/	       	 # 组件集合，用于存放与业务无关的（展示型组件）、可复用的组件
│   	├── xxx/      		  	 # xxx组件
│   		├── components/   	 # 组件独有的子组件，目录结构与父级一致
│   		├── img/      	  	 # 组件的图片目录
│   		├── xxx.jsx	      	 # 组件的jsx文件
│   		├── xxx.scss    	 # 组件的scss文件，按需选择
│   		├── xxx.module.scss* # 组件的scss文件，开启css-modules，按需选择
│   		├── xxx.mdx	  	  	 # 组件的说明文档（功能复杂组件可选）
│   	  	└── index.js 	     # 组件的export
│   	└── index.js    	  	 # 所有组件的统一export
│
│   ├── constants/     		  	 # 常量目录（可选）
      └── index.js	  	  	 # 常量的统一export

│   ├── layouts/     		  	 # 项目布局集合，用于路由分层
│   	├── xxxLayout/  	  	 # xxx布局组件
│   		├── components/   	 # 布局独有的子组件，目录结构与通用组件一致
│   		├── style/    	     # 布局主题scss文件
│   		├── xxx.jsx	      	 # 组件的jsx文件
│   		├── xxx.scss      	 # 组件的scss文件
│   		├── xxx.module.scss* # 组件的scss文件,开启css-modules
│       ├── menuConfig.js 		 # 菜单配置（顶部导航/侧边导航/底部导航等）
│   	  └── index.js 	    	 # 布局的export
│   	└── index.js    	  	 # 布局的统一export
│
│   ├── modules/    		  	 # 业务组件集合（目录结构与layouts一致）
│   	├── xxx/  		  	  	 # 各模块目录
│   	└── index.js	  	  	 # 容器组件相关的统一export
│
│   ├── pages/      		  	 # 页面级组件，用于组合modules/layouts等，目录结构=通用组件
│   	├── xxx/  			  	 # 各页面目录
│   	└── index.js      		 # 页面的统一export
│
│   ├── stores/      		  	 # 数据store相关，与mobx等库配合
│   	├── Store.js    	 	 # 数据层的基础类
│   	├── xxxStore.js  	  	 # 各业务store，需要继承Store基类
│   	└── index.js	  	  	 # store相关的统一export
│
│   ├── utils/      		  	 # 辅助工具集合，项目通用方法、函数等
│   	├── xxx.js  	 	   	 # 各辅助工具
│   	├── polyfill.js    		 # 浏览器补丁相关
│   	└── index.js	  	  	 # 辅助工具类的统一export
│
│   ├── settings.scss			 # 项目scss变量定义，用于重置基础变量
│   ├── App.js      		  	 # 应用入口组件
│   ├── App.css / .scss*
│   ├── App.test.js
│   ├── index.js    		  	 # React入口js
│   ├── index.css / .scss
│   ├── router.js		 	   	 # 全局路由处理逻辑
│   ├── routerConfig.js 		 # 全局路由配置
│   ├── serviceWorker.js
│   ├── setupProxy.js 			 # 全局代理配置
│   └── vendorConfig.js 		 # 用于配置第三方库splitting的范围
│
├── tests/          		  	 # 存放测试用例
├── .babelrc.js			         # babel 自定义配置文件
├── .commitlintrc.js	    	 # 提交日志规范相关
├── .editorconfig       		 # 编辑器配置文件
├── .env		       	      	 # 环境变量配置文件，公共变量配置
├── .env-cmdrc.test.js  		 # 环境变量测试文件
├── .env-cmdrc.js      			 # 环境变量配置文件，不同环境的变量配置
├── .eslintignore     			 # eslint 忽略配置，类似 .gitignore
├── .eslintrc.js       			 # eslint 配置文件
├── .gitattributes     		     # 指定由 git 使用的文件和路径的属性
├── .gitignore          	     # git 提交忽略配置文件
├── .lintmdrc           	     # markdownlint 配置文件
├── .lintstagedrc.js    	     # lint-staged 配置文件
├── .npmignore          	     # npm 提交忽略配置文件
├── .nvmrc             		     # 配置项目所使用的 node 版本（采用nvm管理node版本）
├── .prettierignore     		 # prettier 忽略配置，类似 .gitignore
├── .prettierrc.js   	  		 # prettier 配置文件
├── .stylelintignore	  		 # stylelint 忽略配置，类似 .gitignore
├── .stylelintrc.js			     # stylelint 配置文件
├── .yarnrc              	     # yarn 配置文件
├── config-overrides.js			 # 在不eject的情况下，扩展webpack配置
├── jsconfig.json        	     # 指定根文件和js语言服务提供的功能选项
├── package.json		      	 # 包含项目的基本信息、项目的依赖以及项目的相关执行命令等
├── package-lock.json     	     # npm 依赖包版本lock
├── README.md				     # 描述此项目的功能、特点、API 等信息
├── server.js       	  		 # 本地构建服务器
├── server.test.js  	  		 # 本地开发测试服务器
└── yarn.lock            	     # yarn 依赖包版本lock

以上结构是项目的推荐结构；带有 * 的文件为可选。

以上未提及的文件夹或文件，不用关注。以上各目录中的统一 export 不包括第三方组件，且未使用的组件应避免在此导出。

命名规范

详情参见项目级规范。

组件分类

规范中将组件划分为通用组件和业务组件两大类。

通用组件（复用级别：框架级）

通用组件也叫展示型组件，与具体业务解耦，只负责接收指定格式的数据进行 UI 展示。可在大多数项目中通用。约定存放在**src/components**目录中。

为便于沉淀通用组件库，并提高其可维护性。约定将通用组件划分以下 4 类：

basis：基础型组件，构成网页的基本元素。例如图标、按钮等；
layout：布局型组件，用于组织页面布局，例如网格系统、两侧留白、水平留白等；
block：区块/模块型组件，具有独立的功能，低于页面级的组件，例如支持筛选和分页的表格，可以嵌套；
template：模板型组件，可重用的复杂 UI 结构，一般为页面级组件，例如支付成功页等。

业务组件（复用级别：项目级）

业务组件是指与项目紧密相关的组件，一般会捆绑具体的数据或状态，也叫容器型组件。分为以下 3 类：

modules（src/modules）：功能组件，用于归类项目开发中，无法沉淀为框架级的、但项目内可复用的功能块，一般由数据或状态 + 通用组件组成。例如购物车模块、用户登录等。
pages （src/pages）：页面组件，用于归类按页面流划分的页面组件，一般由项目级 modules + **通用组件（布局类组件等）**组成。

layouts（src/layouts）：结构组件，主要用于对整个项目的页面结构做归类，抽出公共的页面级容器组件。例如可定义：

- MainLayout：用于一级页面，带有一级导航、标题栏、底部导航等。
- BaseLayout：用于二级页面，如商品列表、商品详情等。
- BlankLayout：什么都不带，100%高的容器，用于404 等特殊页面布局等。

当然，也可以根据业务需求划分，如 GoodDetailLayout 商品详情模块、UserLayout 登录/注册/忘记密码等。其原则是可重用，便于组织页面。

开发须知

推荐通过各类目录下的 index.js 统一 export。便于对该目录下的资源或组件进行统一注册、替换和添加描述备注等，提高可维护性。
通过@、@/components、@components 等别名来引入组件。
开发前先根据页面梳理组件，并对组件分级；做好 store 划分，提取公共数据处理逻辑。
尽量做到页面均由布局组件+ 通用组件/项目级功能组件组成，不含原子标签（div、span 等）。

依赖环境

node 8+
babel 7
webpack 4
React 16+
ES6+
node-sass 4+
jest + react-testing-library

安装

默认使用 yarn，npm 可能无法正常安装 node-sass。若yarn安装node-sass失败，可通过cnpm单独安装node-sass。

> yarn

命令行

yarn start/npm start 启动开发环境，会自动在浏览器打开 http://localhost:3000，支持热更新。
yarn build 生产环境打包
yarn test 进行测试
yarn commit 命令行提交，类型选择
yarn version changlog 及版本管理

推荐编辑器 Visual Studio Code，如果出现 vscode 占用系统资源 100%的情况，请检查是否安装了 SCSS InterliSense 、IntelliSense for CSS class names in HTML 插件，若存在，请关闭这类插件。****

开发相关

修改入口页标题

如果要修改网页标题，请修改 package.json 的 title 字段；或者修改 public/index.html 中的<title>标签内容。还可替换 favicon.ico 为自己的 ico。 manifest.json 中的信息也一并修改。

使用全局别名

已定义以下全局别名：@代表src目录、@theme代表当前项目配置的主题（在package.json中配置）;

// package.json
{
  "buildConfig": {
    "theme": {
      "alifd": "@alifd/theme-xxx"
    }
  },
}

使用别名，scss 名称@import 时需要写完整，文件名中的_ 和 .scss 后缀名不能少。使用第三方库的 css 时，可以通过~引入或写全node_modules的路径。

组件的异步加载

默认情况下，webpack 会将引用到的包都打包到同一个 JS 文件中，入口 js 文件体积可能会很大。通过按需加载，可以使之变小。方法引入：

import { lazy } from '@ozo/lazy-loader';
const Login = lazy(() => import('./UserLogin'));

<Route  path='/Login' component={Login}/>

更多用法可查看 @ozo/lazy-loader的使用说明。

组件Import顺序

统一编写习惯，方便团队成员形成统一的“表达“，减轻代码阅读负担。推荐顺序为：

通用基础库：prop-types、classnames、lodash-es等
react基础库：react、react-dom、react-router-dom等
mobx、redux基础库：mobx、mobx-react等
第三方组件库：@alifd/next等，库附带的样式文件跟随其后
项目级组件：@/components/xxx
页面级组件：./components/xxx
项目级工具类：@/utils/xxx
页面样式文件：css、scss文件，注意引入顺序，按影响程度引入，影响最直接的放在最后
图片、json等静态资源，比较多时可考虑单独的文件集中导入/导出管理

webpack生产打包时，scss的顺序是按照代码执行的顺序，谁先import就先打包谁。

设计与开发协同

详情参见UI 设计与前端协同。

CSS 样式编写

定义 SCSS 变量

项目开发中，对于在主题包之外的公共特性，如颜色、字号等，统一定义到src/settings.scss文件中，以便于后期维护和管理。注意命名规范和分组。

// ./src/settings.scss
$modal-color: #f33;

// 组件的xxx.scss
@import '@/settings'; //引入路径根据组件scss文件位置进行修正
.content {
    color: $modal-color;
}

使用 SCSS mixins

脚手架默认引入了一些常用的 mixins，使用方法参考：https://github.com/inier/mixins。

@import '@/settings'; //引入路径根据组件scss文件位置进行修正

/*-------- 极细边框 --------*/
// 上、右、下、左边框
.border-t {
    @include onepx-scale(#eee, top, after, 2px);
}

.border-r {
    @include onepx-scale(#eee, right, after, 2px);
}

此外，也可以在 @/settings.scss 文件中自定义 mixins。

不开启 CSS-Module

css 样式可以选择是否开启 CSS-Module 功能，先介绍不开启的方式。

第 1 步：样式文件命名为 xxx.scss;

.content {
    padding: 10px;
    .logo {
        width: 40px;
    }
}

第 2 步：在 jsx 中引入时使用import './xxx.scss';

import './xxx.scss';
...
<main className="content">
	<div className="logo"></div>
</main>

未开启 CSS-Module 功能，将需要注意避免各组件间的样式冲突，推荐 BEM 命名规范，用法自行搜索。

开启 CSS-Module 功能

第 1 步：样式文件命名为 xxx.module.scss;

.content {
    padding: 10px;
    .logo {
        width: 40px;
    }
}

第 2 步：在 jsx 中引入时使用 import styles from './xxx.module.scss';

...
import styles from './xxx.module.scss';
...
<main className={styles.content}>
	<div className={styles.logo}></div>
</main>

开启 CSS-Module 功能后，将不在支持直接用引号引入该文件的样式；

如果要使用全局样式，请在样式文件中使用 :global，并在引用时，使用字符串而不是变量应用。

样式继承：开启 CSS-Module 功能后，样式继承请使用如下方法。

如果由于某种原因需要禁用 Autoprefixer，请按照本节进行操作。

默认情况下禁用了 CSS Grid(网格) 布局前缀，但不会删除手动前缀。如果你想选择加入 CSS Grid(网格) 前缀，请先熟悉一下它的局限性。要启用 CSS Grid(网格) 前缀，请将 /* autoprefixer grid: on */ 添加到 CSS 文件的顶部。

使用字体图标

引入在线字体图标

推荐使用阿里巴巴 iconfont库来管理项目的图标。

上传好图标后，在网站上生成在线链接（font class），复制该链接，使用它替换掉.env文件中的REACT_APP_ICONFONT_URL字段：

# REACT_APP_ICONFONT_URL="//at.alicdn.com/t/font_xxx_xxx.css"

然后修改public/index.html即可。

<!-- <link rel="stylesheet" href="%REACT_APP_ICONFONT_URL%"> -->
变为
<link rel="stylesheet" href="%REACT_APP_ICONFONT_URL%" />

本地引入方式：[仅自建 CDN 的情况下使用]。在阿里巴巴 iconfont中上传图标，然后在网站上生成在线链接（font class），访问该链接并复制其中的内容。在public目录中新建iconfont.css，将刚复制的内容粘贴到该文件中，然后在public/index.html目录中引入该链接即可。

<link rel="stylesheet" href="./iconfont.css" />

这种方式需要注意 cdn 缓存问题，建议在 CDN 规则中不缓存该文件的图标。对于频繁更新的情况，可以采用其他手段将其 hash 化。

引入本地字体图标文件

对于本地化字体文件，可将该资源放入到src/assets目录中，然后在src/index.scss中引入其样式文件即可。

这种情况下，本地字体图标文件，一般会被完整打包到 js 中，也可通过打包手段分离出来。

平台型协同方式的字体图标（推荐）

采用平台型协同方式时，可在 fusion 平台统一管理字体图标（同样依赖 iconfont.cn 库）。不用单独引入 iconfont.css。

引入图片等资源

为了减小 Http 的请求数目，在打包时 webpack 会将小于 10k 的图片直接转换成 base64 字符串放在 html 中。 目前只支持 bmp,gif,jpg,jpeg,png

写法如下：

import React from 'react';
import logo from './logo.png'; // Tell Webpack this JS file uses this image

console.log(logo); // /logo.84287d09.png

function Header() {
    // Import result is the URL of your image
    return <img src={logo} alt="Logo" />;
}

export default Header;

.Logo {
    background-image: url(./logo.png);
}

配置API调用接口

在本地开发时，前端调用的接口都是跨域的，需要进行代理。将相对路径配./src/api/ApiUrl.js中即可。

// ./src/api/ApiUrl.js

const urls = {
    ...
    POST_LOGIN: '/main/login',
    GET_RESPONSE_CODE: '/resc/list'
    ...
}

API接口命名采用全大写字母，下划线拼接，建议以对应的提交方式GET和POST等冠名，以便直观的显示。

配置开发环境代理

在src/setupProxy.js中参照一下配置：

module.exports = function (app) {
    app.use(
        '/api',
        createProxyMiddleware({
            target: 'http://localhost',
            changeOrigin: true,
            pathRewrite: {
                '^/api': '',
            },
        })
    );
    ...
};

具体代理规则，请先到接口通用处理逻辑中根据自己接口返回结果的格式情况，进行修改。

这样配置后所有带有/api的接口请求都会被代理到http://localhost。具体用法请参考http-proxy-middleware组件的官方用法。

mobx 开发相关

优先使用最新版本的mobx5，该版本采用 Proxy 对象，部分机型不支持。对兼容性有要求的可以降低到mobx3、或mobx4（支持 es5）。详情请参考mobx 开发手册。

mobx 开启严格模式

mobx 开启严格模式，必须使用@action 来修改数据

// mobx5，匹配mobx-react6.x，  //https://cn.mobx.js.org/refguide/api.html  +  https://blog.csdn.net/smk108/article/details/83185745
configure({
    enforceActions: 'observed',
});

// mobx4，匹配mobx-react5.x
configure({
    enforceActions: true,
});

// mobx3及以下，匹配mobx-react4.x
useStrict(true);

注意与之搭配的mobx-react库。

开启/关闭 sourcemap

cra 通过 GENERATE_SOURCEMAP 来控制 sourcemap 的开启和关闭，在.env-cmdrc.js 文件中对应的环境下，增加"GENERATE_SOURCEMAP": false, false 为关闭 sourcemap，true 为开启 sourcemap。

{
  "development": {
    "REACT_APP_HMR": false
  },
  "production": {
    "GENERATE_SOURCEMAP": false,
    "BUNDLE_VISUALIZE": true
  },
  "test": {
  },
  "uat": {
    "PORT": 8080
  }
}

启用 PWA 特性

CRA 支持 workbox，可以一键开启 PWA（Progressive Web App）。在src/index.js 文件中有以下代码：

serviceWorker.unregister();

如果要使用 CRA 提供的 PWA 特性的话，我们需要将serviceWorker.unregister() 改为serviceWorker.register()。打包项目后，在build文件夹下有以下几个文件：

asset-manifest.json // 存放本次打包后资源的路径及 hash，用于区分版本
server-worker.js // 规定了资源缓存策略
preche-manifest.xxxxxxxxx.js // 静态资源版本记录
manifest.json // Web 应用程序清单,可以配置在系统桌面上的图标等，参考文档

在 src 文件目录下有一个 serviceWorker.js 文件，用于检查环境变量是否为“production”，且当前浏览器是否兼容 service worker。

代码检查

本工程中采用的检查工具包括：

ESLint：用于检查 js 的逻辑错误；
Prettier：用于格式化 js 的格式；
Stylelint：用于检查css、scss等样式的语法和书写等。

ESLint 禁用检查

http://eslint.cn/docs/user-guide/configuring#disabling-rules-with-inline-comments

Stylelint 禁用检查

跟 eslint 类似，通过 stylelint-disable 注释来局部禁用某一项规则。通过 stylelint-enable 可以把之前忽略的规则重新开启。一定要注意，只 enable 对应的规则，形成呼应：

<style>
    .classA {
        /* stylelint-disable declaration-block-no-duplicate-properties */
        transition-property: transform;
        transition-property: transform, -webkit-transform;
        /* stylelint-enable declaration-block-no-duplicate-properties */
    }
</style>

低版本浏览器兼容

详情参见低版本浏览器兼容。

本地调试

使用 VSCode 调试

本工程可以使用 VSCode 进行调试。但需要先安装这个Debugger for Chrome

测试相关（待更新）

单元测试

测试：yarn test 或者 npm test，详情请参考create-react-app 官方文档。

集成测试/功能测试/性能测试/渲染测试 @testing-library/react 测试React Component的库 @testing-library/react-hooks 测试自己写的的React Hooks的库 @testing-library/jest-dom 提供更多利于dom测试的断言

代码提交

提交时自动格式化

只有使用 Git 作为代码服务器时有效

使用以下插件 husky lint-staged prettier 实现在提交代码时，自动进行格式化 To format our code whenever we make a commit in git, we need to install the following dependencies:

规范提交记录

使用一个规范的提交记录是很有必要的，这不仅让多人开发中的参与者能更好地了解项目的迭代历史和进程，也能在出现问题时快速定位，找到问题代码的提交记录。

在提交代码时，应遵守以下规范：

修改的文件如果涉及多个板块，应单独先提交。
规范提交信息格式：(): ,具体参考提交记录规范指南。例如:

    fix(发票信息页面):修改返回字段。
    feat(SingleInput组件):扩展xxx功能，增加size属性用于设置输入框高度，默认为md [44px]，目前支持lg [54px]
    chore: 新增scss支持（支持 scss 并兼容css-modules）

自动生成更新说明（待更新）

此外，还可以使用工具根据提交记录自动生成更新说明 (CHANGELOG)，免去手动更新的痛苦，也方便用户了解每次更新的具体内容。具体参考更新说明规范指南。

构建发布

构建：yarn build或npm run build，App 构建出发布的文件到 build 目录。
发布：将 build 目录下的文件发布到对应node服务器上即可；该环节推荐通过搭建 CI/CD 平台来自动完成。

Code Review

CodeReview 的目的是提升代码质量，尽早发现潜在缺陷与 BUG，降低修复成本，同时促进团队内部知识共享，帮助更多人更好地理解系统，这也是帮助新人成长最快的方式之一。详情参考CodeReview 规范。

参考文章：

https://www.zhihu.com/question/41089988?sort=created

https://blog.csdn.net/uxyheaven/article/details/49773619

http://www.cnblogs.com/cnblogsfans/p/5075073.html

进阶配置

国际化

项目的国际化，根据场景主要分为组件国际化、日期国际化、内容国际化。

组件国际化

很多 UI 框架或组件自身已提供国际化方案，可以参考使用，如Fusion Design UI。

日期国际化

对于日期来说，可以借助 moment 库，其自带国际化相关能力。目前社区比较主流的解决方案有以下两种：

方法一：

const webpack = require('webpack');

module.exports = {
    // ...
    plugins: [
        // 打包指定需要的语言文件
        new webpack.ContextReplacementPlugin(/moment[\/\\]locale$/, /zh-cn|ja/),
    ],
};

方法二：

const webpack = require('webpack');

module.exports = {
    // ...
    plugins: [
        // 只打包有过引用的语言文件，应用中需要添加如：`import 'moment/locale/zh-cn';`
        // new webpack.IgnorePlugin(/^\.\/locale$/, /moment$/)
    ],
};

内容国际化

主流的内容国际化方案有：

kiwi [有配套的 vscode 工具，持续关注]

react-intl [yahoo]

react-intl-universal [alibaba]

react-i18next [i18next.js]

i18n-pick [蚂蚁金服团队]

react-i18n [腾讯 webnovel 团队，暂未开源]

自定义 webpack 配置

本脚手架采用了 react-script，自定义 webpack 的配置有两种方式：

**eject：**该方式可获得 webpack 的完全控制权，具体用法参见[http://www.geekjc.com/post/5b74e06ac827d41a704bac62(http://www.geekjc.com/post/5b74e06ac827d41a704bac62)
**不 eject：**推荐方式，引入react-app-rewired和customize-cra插件，具体用法请参见： https://github.com/timarney/react-app-rewired / https://github.com/arackaf/customize-cra

添加自定义的环境变量

你可以在工程设置环境变量，默认的环境变量有 NODE_ENV，它的值有development / production / test 分别对应运行的命令行yarn start / yarn build / yarn test。

环境变量的值会在打包阶段被动态的替换掉；要在 React 的环境下生效，自定义的环境变量必须以 REACT_APP_ 开头；不以 REACT_APP_开头的自定义环境变量，只会在后续执行的 nodejs 脚本中生效，而不会置入到 React 的运营环境中。例如 BUNDLE_VISUALIZE，只能用于开启脚手架中的webpack-bundle-analyzer。

设置环境变量

环境变量有以下几种设置方式：

env-cmd 的 rc 文件集中管理（推荐）

使用env-cmd工具可以方便的对文件进行管理。

安装 env-cmd
在根目录新建**.env-cmdrc.js**文件，用于自定义不同环境的环境变量，这里配置的变量会覆盖.env.local文件中的对应变量，内容类似：
```
{
  "development": {
  },
  "test": {
  },
  "production": {
    "BUNDLE_VISUALIZE": "1"
  },
   "h5": {
    "PORT": 8080
  }
}
```

在 package.json 中注册脚本命令，根据自己的需要指定环境，多个环境可以共用，用,分隔：

"scripts": {
    "start": "env-cmd development,h5 react-app-rewired start",
    "build": "env-cmd production react-app-rewired build",
    "test": "env-cmd test react-app-rewired test",
    ...
}

如果需要自定义通用环境变量，可在根目录新建**.env.local**文件，内容类似：

# NODE_ENV=development
# PORT=3000
# API_SERVER=192.168.0.100
# API_PORT=9000

# 应用名称
REACT_APP_TITLE=toxic
# 应用版本
REACT_APP_VERSION=1.0

文件内定义

可以在项目根目录下新建如下的文件（不同命令，会读取不同的文件）

.env：默认使用
.env.local：用于本地变量覆盖，这个文件会在除了test环境的所有环境加载
.env.development,.env.test,.env.production：在对应的环境加载
.env.development.local,.env.test.local,.env.production.local：在对应的环境加载，最高优先级，会覆盖.env.*的配置

加载的优先级从高到低，依次为：

npm start: .env.development.local, .env.development, .env.local, .env
npm run build: .env.production.local, .env.production, .env.local, .env
npm test: .env.test.local, .env.test, .env (注意没有 .env.local)

命令行直接设置

环境变量还可以在运行命令行的时候直接设置

Windows(cmd.ext): set REACT_APP_SECRET_CODE=123&&npm start
Mac: REACT_APP_SECRET_CODE=123 npm start

使用环境变量

jsx 中使用：

render() {
  return (
    <div>
      <small>You are running this application in <b>{process.env.NODE_ENV}</b> mode.</small>
      <form>
        <input type="hidden" defaultValue={process.env.REACT_APP_SECRET_CODE} />
      </form>
    </div>
  );
}

js 中使用：

if (process.env.NODE_ENV !== 'production') {
    analytics.disable();
}

html 中使用：

<title>%REACT_APP_WEBSITE_NAME%</title>

在开发中使用 https

通过环境变量设置

module.exports = {
    development: {
        ...
        // 在开发环境中使用 HTTPS, 默认未开启
        HTTPS: true,
    },
    ...
}

Windows (cmd.exe)

set HTTPS=true&&npm start

(Note: the lack of whitespace is intentional.)

Linux, macOS (Bash)

HTTPS=true npm start

应用第三方 JS

node 模块引用

使用 npm 安装后，直接在 js 文件中 import 即可。

单个 JS 文件引用

如果文件符合 AMD/CMD 规范可以直接 import，如果不符合请在 public/index.html 中引入

附录

开发规范

关于工程目录介绍和代码规范等。

前端开发规范

bug 记录

记录各种 bug。

bug 记录

踩坑日记

存放各种坑及填坑方法。

踩坑日记

@ozo/react-rock

React 模板工程

技术特性

项目规范

文件结构

命名规范

组件分类

通用组件（复用级别：框架级）

业务组件（复用级别：项目级）

开发须知

依赖环境

安装

命令行

开发相关

修改入口页标题

使用全局别名

组件的异步加载

组件Import顺序

设计与开发协同

CSS 样式编写

定义 SCSS 变量

使用 SCSS mixins

不开启 CSS-Module

开启 CSS-Module 功能

使用字体图标

引入在线字体图标

引入本地字体图标文件

平台型协同方式的字体图标（推荐）

引入图片等资源

配置API调用接口

配置开发环境代理

mobx 开发相关

mobx 开启严格模式

开启/关闭 sourcemap

启用 PWA 特性

代码检查

ESLint 禁用检查

Stylelint 禁用检查

低版本浏览器兼容

本地调试

使用 VSCode 调试

测试相关（待更新）

单元测试

代码提交

提交时自动格式化

规范提交记录

自动生成更新说明（待更新）

构建发布

Code Review

进阶配置

国际化

自定义 webpack 配置

添加自定义的环境变量

设置环境变量

env-cmd 的 rc 文件集中管理（推荐）

文件内定义

命令行直接设置

使用环境变量

在开发中使用 https

通过环境变量设置

Windows (cmd.exe)

Linux, macOS (Bash)

应用第三方 JS

node 模块引用

单个 JS 文件引用

推荐库

附录

开发规范

bug 记录

踩坑日记

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Weekly Downloads