02.初始化Three.js项目

02初始化Three.js项目

本文以Yarn而不是NPM安装Three.js。

第1步：全局安装create-react-app

yarn global add create-react-app

第2步：初始化React+TypeScript项目

我用的是create-react-app 4.0.2版本，对应的是React 17.0.1

yarn create react-app test-threejs --template typescript

第3步：初次修改tsconfig.json配置

修改TS编译目标ES版本为es2017
```
"target": "es2017"
```

添加一些本人TS配置偏好

"noUnusedLocals": true,
"noUnusedParameters": true,
"sourceMap": true,
"removeComments": false

第4步：配置alias，安装对应模块

由create-react-app创建的React项目中，配置alias(路径映射)，我采用的方案是：react-app-rewired + react-app-rewire-alias

yarn add --dev react-app-rewired react-app-rewire-alias

第5步：完善alias配置

在项目根目录，新建文件tsconfig.paths.json，内容暂时设置为：
```
{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@/src/*": ["./src/*"],
            "@/components/*": ["./src/components/*"]
        }
    }
}
```
我们暂时先添加2个路径映射src和components，具体路径还会根据将来实际开发过程中所需要创建不同的目录结构进行修改。

补充：根据typescript官方更新说明文档，baseUrl这一项是可以省略的，但是上面代码中还是遵循了之前的配置方式，继续添加上了baseUrl。
在项目根目录，新建文件config-overrides.js，内容为：
```
const { alias, configPaths } = require('react-app-rewire-alias')

module.exports = function override(config) {
  alias(configPaths('./tsconfig.paths.json'))(config)

  return config
}
```
注意是.js文件而不是.ts文件，鼠标放到require上后也许会显示提示文字：文件是CommonJS模块；它可能会转换为ES6模块。

请忽略这个提示，这并不是什么错误信息。

require是Nodejs导入模块的方式，TypeScript导入模块使用的是import。

在项目根目录，新建文件global.d.ts，内容为：

注意：本步骤的目的是为了让TS忽略对react-app-rewire-alias和其他一些非常规格式文件的导入检查。

本步骤是可选的，不是必须的，你可以跳过本步骤。

declare module '*.png';
declare module '*.gif';
declare module '*.jpg';
declare module '*.jpeg';
declare module '*.svg';
declare module '*.css';
declare module '*.less';
declare module '*.scss';
declare module '*.sass';
declare module '*.styl';
declare module 'react-app-rewire-alias';

修改tsconfig.json文件，添加以下一行内容：

{
  "extends": "./tsconfig.paths.json",
  "compilerOptions": {
    ...
  }
}

请注意extends是和compilerOptions平级的。

至此，我们的tsconfig.json最终内容如下：

{
  "extends": "./tsconfig.paths.json",
  "compilerOptions": {
    "target": "es2017",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "sourceMap": true,
    "removeComments": false
  },
  "include": [
    "src"
  ]
}

第6步：修改package.json中的scripts命令

将命令中start、build、test 3条命令中的react-scripts修改为react-app-rewired

"scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
    "eject": "react-scripts eject"
  },

第7步：安装scss

yarn add node-sass --dev

假设你使用的是较早版本的create-react-app，那么当时还不支持最新版node-sass 5.0，所以你只能安装： yarn add node-sass@4.14.1 --dev

第8步：安装three.js

//npm install --save three
yarn add three

以下更新于2021.04.11

关于.d.ts文件的特别说明：

写这篇文章的时候是2020年11月底，当时应该是r124版本，当时的Three.js版本里内置了.d.ts文件，但是随着Three.js版本升级，大约在r126版本以后官方已经将内置的.d.ts文件移除，目前最新的版本是r128。

所以，我们现在还需要额外安装对应的.d.ts文件包：

//npm install @types/three
yarn add @types/three

本系列教程前面相当一部分示例是基于Three.js 0.124.0的，而这些示例有可能会在最新版本0.127.0中不能正常运行，特此说明。

所谓不能正常运行，多数都是因为某些类在新版本中引入路径发生了变化，可根据VSCode中的提示进行修改。

我们会在第23小节开始，使用Three.js最新版本r127。

以上更新于2021.04.11

第9步：给package.json添加homepage字段

{
  "name": "test-threejs",
  "homepage": ".",
  ...
}

homepage字段是用来设定html中文件资源(编译后的js或css)的根URL地址。

假设不添加homepage字段，则默认使用网站根目录作为资源根目录。

我猜测homepage的默认值是 “/”

如果你的项目将来并不是发布在网站根目录，那么设置homepage字段会非常有用。

举例：

假设将来项目网址为：https://threejs.puxiao.com，那么你完全可以跳过本步骤，不作任何修改。

但若将来项目网址为：https://threejs.puxiao.com/demo/，那么此时所有文件资源存放在demo这个目录下(并不是网站根目录)，那么必须给package.json添加 “homepage”: “."，不然文件资源都会出现404状态。

第10步：清理默认create-react-app创建的一些无用内容

以下为我个人的习惯，你可以根据自己喜好对应选择是否清理。

清除掉index.tsx中<React.StrictMode> 、reportWebVitals()

目前React最新版中对应的tsconfig.json默认就使用的是严格模式，因此<React.StrictMode>是可以删除掉的
删除掉src目录下setupTests.ts、reportWebVitals.ts、App.test.tsx文件

这些都是用来做React自动单元调试的，暂且用不到
删除掉public目录下logo192.png、logo512.png、manifest.json、robots.txt

清除掉public目录下index.html中无用的代码，只保留最基础的标签。

<!DOCTYPE html>
<html lang="zh-CN">

<head>
  <meta charset="utf-8" />
  <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="theme-color" content="#000000" />
  <meta name="description" content="Web site created using create-react-app" />
  <title>Hello Threejs</title>
</head>

<body>
  <noscript>You need to enable JavaScript to run this app.</noscript>
  <div id="root"></div>
</body>

</html>

经过以上10个步骤之后，已经创建好了一个基础的开发环境：React + TypeScript + Scss + Alias + Threejs

下一章，终于要开始编写hello world了。

最近更新于0001-01-01