升级至V6

本文摘录了reSKRipt V5 -> V6版本的所有破坏性变更，如果你正在使用5.x版本，可以参考本文进行升级。如果你在升级过程中遇到任何困难，欢迎在GitHub上提交Issue来咨询。

V5的主要变化是调整了Webpack的产出结构，并更新了Vite、Jest、Antd的支持版本。

自动检测

你可以先使用我们的迁移脚本对项目做一次快速地扫描：

# 保持在项目根目录下
npx @reskript/doctor migrate

按照报告的说明进行修复后，如果依然有问题，以下是各变更的详细介绍。

依赖升级

你需要将@reskript/*的包均升级到5.x最新版。你的package.json的变化大致如下：

{
    "devDependencies": {
-        "@reskript/cli": "5.7.4",
-        "@reskript/cli-build": "5.7.4",
-        "@reskript/cli-dev": "5.7.4",
-        "@reskript/cli-lint": "5.7.4",
-        "@reskript/cli-play": "5.7.4",
-        "@reskript/cli-test": "5.7.4",
-        "@reskript/config-lint": "5.7.4",
+        "@reskript/cli": "6.0.0",
+        "@reskript/cli-build": "6.0.0",
+        "@reskript/cli-dev": "6.0.0",
+        "@reskript/cli-lint": "6.0.0",
+        "@reskript/cli-play": "6.0.0",
+        "@reskript/cli-test": "6.0.0",
+        "@reskript/config-lint": "6.0.0",
+        "@reskript/settings": "6.0.0",
    }
}

NodeJS版本

V4要求你的NodeJS版本为>= 16.10.0，即必须是14.10.0以上的版本，我们推荐使用fnm来管理NodeJS版本。

Webpack产出结构升级

在以往版本中，Webpack的产出根目录为dist/assets，并通过将HTML放置在../xxx.html来模拟出dist文件夹的结构，这使得我们在与社区更多工具融合时遇到了各类麻烦，诸如：

1. 使得publicPath的路径在不同的引擎（Webpack或Vite）下处理方式不同，切换引擎后需要同步修改。
2. 用户自主引入的Webpack插件在配置中读取的output配置是dist/assets，难以正确地处理。

在V6版本中，我们修正了这一问题，将产出根目录更改为dist，并将各类资源（.css、.js、.svg等）放置在dist/assets下。

如果没有自定义配置，你在构建后的dist目录结构会保持不变，HTML文件依然为dist/xxx.html，其它资源依然为dist/assets/*。

在此有只有一个例外，你的favicon文件将从dist/assets/favicon.ico变为dist/favicon.ico，这使得favicon会发布在Web服务器的根目录下，对于会自动抓取/favicon.ico的爬虫、浏览器等客户端更加友好。

如果你有自定义配置，且修改过publicPath，无论是通过reSKRipt配置中的build.publicPath还是通过build.finalize直接修改Webpack的配置，你都需要做出相应的修改。通常来说，你原来的publicPath应该是以/assets/结尾的，在更新至V6版本后，请将末尾的assets/部分去除。

如你原来的publicPath为https://my-cdn.com/project-name/assets/，相应修改为https://my-cdn.com/project-name/即可。

如果你有进行入口配置，即存在src/entries/**/*.config.{ts,mjs}文件，请检查这些文件中的配置。如果存在导出的配置有entry.filename属性，需要进行相应的修改。

在V5及以下版本中，如果你的entry.filename配置为foo.js，那么构建而成的文件会放置在dist/assets/foo.js下，在V6版本中则会变为dist/foo.js。如果要保持位置，请将entry.filename加上assets/前缀，即从foo.js修改为assets/foo.js。

工具版本更新

在V6版本中，一系列的社区工具版本进行了更新。

Vite

Vite更新至4.x，且内置了@vitejs/plugin-legacy，默认关闭，你可以通过build.legacy: true来启用。

正常情况下，你无需关心具体的升级点，只需要将项目中的vite版本更新至最新那可。

具体的Vite升级变更，请参考Vite版本升级说明。

Webpack

V6版本原则上没有对Webpack的版本要求进行更新，但如果你使用NodeJS的纯ESM模式编写TypeScript代码，即使用import './foo.js'的方式引入foo.ts文件，那么需要将Webpack版本升级至5.74.0以上，才能够使用Webpack内置的ESM模块定位。

Jest

Jest版本更新至29.x，这会使得你原有的测试快照出现一部分失效，你可以通过skr test -u来更新快题。具体的更新点请参考Jest版本升级说明。

同时，我们在V6中移除了enzyme的支持，如果你的测试依赖于enzyme，则需要进行修改。我们建议使用@testing-library/react来进行React组件的单元测试。

Stylelint

Stylelint版本更新至15.x，根据官方的迁移说明，部分编程风格型的规则会被废弃。reSKRipt已经提前将这些规则迁移并使用stylelint-stylistic包实现。

如果你有自定义的stylelint.config.cjs等配置文件，且内部定义了rules配置，使用了stylelint-stylistic声明的规则，需要在规则名前加上stylistic/前缀。

 module.exports = {
     extends: require.resolve('@reskript/config-lint/config/stylelint'),
     rules: {
-        'unit-case': null,
+        'stylistic/unit-case': null,
     },
 };

Antd支持变更

随着Antd 5.x的发布，reSKRipt也在V6版本中进行了相应的更新。

在V6版本中，默认取消了对antd的特殊支持。如果你正在使用antd 5.x版本，则可以无痛地更新并继续使用。

如果你依然在使用antd 4.x版本，你可以在build.uses数组中增加"antd@4"这一项来继续启用对antd的编译优化。

需要注意的是，如果你引入"antd@4"的支持，则默认的build.uses配置会失效，如果你同时还使用lodash,则要把"lodash"也加入到数组中。以下是一个最简化的配置代码：

import {configure} from '@reskript/settings';

export default configure(
    'webpack',
    {
        build: {
            uses: ['antd@4', 'lodash'],
        },
    }
);

除此之外，reSKRipt也取消了less-plugin-functions的支持，如果你有less函数依赖于它，建议寻找其它解决方案，或保持使用V5版本。