升级到 v10

¥Upgrading to v10

这是从 v9 升级到 v10 的迁移指南。

¥This is the migration guide for upgrading from v9 to v10.

提示

v10 尚未发布。本页面包含 v10 中正在进行的重大更改列表。

¥v10 has not yet been released. This page contains a work-in-progress list of breaking changes in v10.

不是你要找的版本？

• 升级到 v9

  ¥Upgrading to v9

• 升级到 v8

  ¥Upgrading to v8

• 升级到 v7

  ¥Upgrading to v7

• 升级到 v6

  ¥Upgrading to v6

一般重大变化

¥General Breaking Changes

Node v18 不再受支持

¥Node v18 No Longer Supported

由于 Node.js v18 已达到其 end-of-life 级别，因此对 Node.js v18 的支持已停止。Faker.js v10 至少需要 Node.js v20.19.0、v22.13.0 或 v24.0.0。

¥Support for Node.js v18 has been discontinued, as this version has reached its end-of-life. Faker.js v10 requires a minimum of Node.js v20.19.0, v22.13.0, or v24.0.0.

CommonJS 仍然受支持，但请检查你的 Node 版本

¥CommonJS Still Supported, but Check Your Node Version

从技术上讲，Faker v10 现在是仅限 ESM 的软件包。不过，好消息是，由于 Node.js 最新版本中引入了 ESM 模块所需功能 策略，你仍然可以在 CommonJS 项目中使用它，而无需更改代码。

¥Technically, Faker v10 is now an ESM-only package. However, the good news is that you can still use it from your CommonJS projects without code changes, thanks to the ESM Modules require feature in recent versions of Node.js.

如果你使用的是 Node 20 或 Node 22，请确保你使用的是足够新的次要版本 - 需要 Node v20.19+ 或 Node v22.13+。

¥If you are using Node 20 or Node 22, ensure you are using a sufficiently recent minor version—Node v20.19+ or Node v22.13+ is required.

const { faker, fakerES } = require('@faker-js/faker'); // this still works

如果你的 Node.js 版本太旧，你可能会看到类似以下错误：

¥If your version of Node.js is too old, you may see an error like:

Uncaught:
Error [ERR_REQUIRE_ESM]: require() of ES Module <path>/faker/dist/index.js not supported.
Instead, change the require of index.js in null to a dynamic import(), which is available in all CommonJS modules.

已弃用代码移除

¥Removal of Deprecated Code

v9 中已弃用的许多方法已在 v10 中完全移除。为了准备升级，建议首先升级到最新版本的 v9（例如 npm install --save-dev faker@9），并修复代码发出的任何弃用警告。

¥A number of methods that were deprecated in v9 have been completely removed in v10. To prepare for the upgrade, it is recommended to first upgrade to the latest version of v9 (e.g., npm install --save-dev faker@9) and fix any deprecation warnings issued by your code.

已移除的方法	替换
faker.address.*	faker.location.*
faker.name.*	faker.person.*
faker.internet.userName	faker.internet.username

某些方法没有精确的替换，因此请仔细检查你的代码。

¥Some methods do not have exact replacements, so check your code carefully.

已移除的方法	替换/说明
faker.internet.color	faker.color.rgb
faker.image.urlPlaceholder	faker.image.dataUri
faker.finance.maskedNumber	参见 #3201
faker.image.avatarLegacy	faker.image.avatar

Word 方法默认解析策略

¥Word Methods Default Resolution Strategy

word 模块中方法的默认解析策略已更改为 'fail'。这意味着，如果不存在符合你输入条件的单词，word 模块中的方法将抛出错误。

¥The default resolution strategy for the methods in the word module changed to 'fail'. This means that methods in the word module will throw an error if no words for your input criteria exist.

// There are no nouns between 20-25 characters long in the word list
faker.word.noun({ length: { min: 20, max: 25 } });
// In v9, this would return a random noun of any length, like 'plastic'
// In v10, this throws an error `FakerError: No words found that match the given length.`

以前，这些方法会返回一个随机单词，完全忽略你指定的长度要求。如果你想恢复此行为，可以为单词方法提供 'any-length' 策略。

¥Previously, the methods would return a random word, completely ignoring the the length requirements you specified. If you want to restore this behavior, you can provide the 'any-length' strategy to the word methods.

v9 中的方法	v10 中的方法具有 v9 的行为
faker.word.adjective()	faker.word.adjective({ strategy: 'any-length' })
faker.word.adverb()	faker.word.adverb({ strategy: 'any-length' })
faker.word.conjunction()	faker.word.conjunction({ strategy: 'any-length' })
faker.word.interjection()	faker.word.interjection({ strategy: 'any-length' })
faker.word.noun()	faker.word.noun({ strategy: 'any-length' })
faker.word.preposition()	faker.word.preposition({ strategy: 'any-length' })
faker.word.sample()	faker.word.sample({ strategy: 'any-length' })
faker.word.verb()	faker.word.verb({ strategy: 'any-length' })