npm run dev 是“本地运行我的网站”的标准,但它是如何工作的呢?我们如何扩展它的功能?在这篇文章中,我们将看看:
- 如何配置 npm run dev 的功能。
- 如何将复杂的命令分解为细粒度的单元。
- 如何并行运行多个命令。
- 如何在不失去正常 ctrl-c 行为的情况下运行先决条件。
- 启动 convex 后端时如何添加种子数据(如果不存在)。
作为一个激励示例,以下是凸帮助程序示例应用程序中定义的一些脚本。我们将介绍每个部分的作用
"scripts": { "dev": "npm-run-all --parallel dev:backend dev:frontend", "build": "tsc && vite build", "dev:backend": "convex dev", "dev:frontend": "vite", "predev": "convex dev --until-success", "test": "vitest" },
它们的定义方式和位置
npm run 运行项目工作区中 package.json 中定义的命令。当您从 npm create vite@latest 等命令启动存储库时,这些命令通常是预先配置的,其中的命令为:
- dev:运行开发环境。这通常包括在文件更改时自动重新加载 ui。对于 vite 来说,这是 vite,next.js 是下一个 dev。
- build:构建用于部署的网站。这通常会编译并捆绑所有 html、css 和 javascript。对于 vite,这是 vite 构建,next.js 是下一个构建。
- test:运行测试 – 如果您使用 jest,则只需“test”:“jest”或 vitest for vitest。
这是来自 next.js 的基本示例:
// in package.json { // ... "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint" }, //...
在这里你可以运行 npm run dev 或 npm run lint 等
您可以在文档中了解有关 npm run 的更多信息。
为什么使用脚本?
这是一个公平的问题,为什么人们会将已经如此简单的命令放入包脚本中。为什么不直接调用 jest 或 vite 或 next build 呢?有几个很好的理由:
- 您可以保存命令的默认参数,这样您就不必记住或记录启动某项操作的“标准”方式。我们将在下面看到如何将其配置为链接命令并并行运行其他命令。
- 它允许您轻松运行由 npm 安装但无法从 shell(终端)全局访问的命令。1 当您安装 npm install -d vitest 之类的东西时,它会将 vitest 安装到 node_modules/.bin 中。2你不能直接在 shell 中运行 vitest,3 但你可以有一个像这样的配置: “scripts”: { “test”: “vitest” } 并且 npm run test 将运行 vitest.
- 即使您位于子目录中,它也始终以包文件夹的根目录作为“当前目录”运行。因此,您可以定义一个类似 “foo”: “./myscript.sh” 的脚本,它总是会在包根目录中(与 package.json 位于同一目录中)查找 myscript.sh。注意:您可以通过 init_cwd 环境变量访问当前调用的目录。
- 当脚本从 npm run 运行时,您可以轻松引用 package.json 中的变量。例如,您可以使用 npm_package_version 环境变量访问包的“版本”,例如 js 中的 process.env.npm_package_version 或脚本中的 $npm_package_version 。
- 如果你有多个工作区(许多目录都有自己的 package.json,并通过“workspaces”配置配置到父 package.json 中),你可以使用 npm test –workspaces 或使用 npm run 在所有工作区中运行相同的命令lint –workspace 应用程序/web.
npm run dev 可以与yarn/pnpm/bun一起使用吗?
是的!即使您使用其他包管理器安装依赖项,您仍然可以使用 npm 运行包脚本。
yarn # similar to `npm install` npm run dev # still works!
您不必记住 npm run dev 映射到yarn dev(或yarn run dev)。 npx 也是如此:无论您使用什么包管理器来安装东西,npx 凸开发都可以工作。
并行运行命令
有几个包可以用来同时运行命令:4
- npm-run-all
- 同时
我们在这里只看一下 npm-run-all 。考虑我们的例子:
"scripts": { "dev": "npm-run-all --parallel dev:backend dev:frontend", "dev:backend": "convex dev", "dev:frontend": "vite", },
这定义了三个脚本。
- npm run dev:后端运行凸开发。
- npm run dev:frontend 运行 vite。
- npm run dev 通过 npm-run-all 并行运行凸开发和 vite。
两个输出都会流出,并且执行 ctrl-c 会中断两个脚本。
预开发?后期构建?
您可以通过将命令命名为 prex 或 postx 来指定在另一个命令(例如 x)之前(前)或之后(后)运行的命令。在示例中:
"scripts": { "dev": "npm-run-all --parallel dev:backend dev:frontend", "dev:backend": "convex dev", "dev:frontend": "vite", "predev": "convex dev --until-success", },
这将在 npm-run-all –parallel dev:backend dev:frontend 的“dev”命令之前运行凸开发 –until-success。
用“&&”链接
对于习惯 shell 脚本的人来说,如果前一个命令成功,则可以按顺序运行两个命令:commanda && commandb。这适用于 windows 和 unix (mac / linux)。
但是,仅使用预先脚本有几个优点:
- 您可以使用 npm run dev –ignore-scripts 运行任一命令以不执行“predev”脚本,或者 npm run predev 显式地仅执行“predev”步骤。
- 根据我的经验,ctrl-c 的行为更容易预测。在不同的 shell 环境中,执行 ctrl-c(向当前进程发送中断信号)有时会终止第一个脚本,但仍运行第二个脚本。经过多次尝试,我们决定切换到“predev”作为模式。
首先运行交互式步骤
对于 convex,当您第一次运行 npx 凸开发(或使用上述脚本的 npm run dev)时,如果您还没有登录,它会要求您登录;如果尚未登录,它会要求您设置项目设置。这很棒,但是当多个命令同时传输输出时,更新输出文本的交互式命令不能很好地工作。这是在 npx 凸 dev 之前运行 npx 凸 dev –until-success 的动机。
- 只要函数和模式与您部署的内容不匹配,凸开发就会同步您的函数和模式,并监视文件更改。
- –until-success 标志仅同步您的函数和模式,直到成功一次,告诉您如果出现问题要修复什么,并自动重试,直到成功或您按 ctrl-c 为止。
- 通过运行 npx凸开发 –until-success,我们可以在尝试启动前端和后端之前完成登录、项目配置和初始同步。
- 如果初始同步发现了诸如缺少环境变量之类的问题(需要在应用程序运行之前进行设置),那么它会特别有用。
- 这样,在后端准备好使用其期望的函数版本处理请求之前,前端不会启动。
启动时播种数据
如果您将 convex 的“predev”命令更改为包含 –run ,它将在前端启动之前运行服务器端功能。
"scripts": { //... "predev": "convex dev --until-success --run init", //... },
–run init 命令将运行凸/init.ts 中默认导出的函数。您还可以运行 –run myfolder/mymodule:myfunction。请参阅此处有关命名的文档。请参阅这篇关于播种数据的文章,但要点是您可以定义一个内部突变来检查数据库是否为空,如果是,则插入一组记录以用于测试/设置目的。
tsc?
如果您使用 typescript,您可以使用裸 tsc 运行类型检查/编译您的 typescript 文件。如果您的 tsconfig.json 配置为发出类型,它将写出类型。如果没有,它只会验证类型。作为构建的一部分,这非常好,因此您不会构建任何有类型错误的东西。这就是上面例子的原因:
"build": "tsc && vite build",
如何传递参数?
如果您想将参数传递给命令,例如将参数传递给测试命令以指定要运行的测试,您可以在after之后传递它们 – 以将命令与参数分开。从技术上讲,你不需要 — 如果你的参数是位置参数而不是 — 前缀,但总是这样做也没什么坏处,以防你忘记为哪个而做。
npm run test -- --grep="pattern"
概括
我们研究了一些使用 package.json 脚本来简化工作流程的方法。谁知道一个简单的 npm run dev 背后可以蕴含多少力量?看看我们原来的例子:
"scripts": { "dev": "npm-run-all --parallel dev:backend dev:frontend", "build": "tsc && vite build", "dev:backend": "convex dev", "dev:frontend": "vite", "predev": "convex dev --until-success", "test": "vitest" },
- dev 在 predev 之后并行运行前端和后端。
- build 在构建静态站点之前通过 tsc 进行类型检查。
- dev:backend 在您编辑文件时不断将后端功能部署到您的开发环境。
- dev:frontend 运行一个本地前端服务器,它会在您编辑文件时自动重新加载。
- predev 在 dev 之前运行,并根据需要进行初始部署、处理登录、配置和初始同步。
- test 使用 vitest 来运行测试。注意:npm test 是 npm run test 以及其他命令的简写,但它们是特殊情况。 npm run test 是我建议的习惯。
-
输入 npm 时 shell 查找要运行的命令的方法是检查 shell 的 path 环境变量(无论如何在 unix 机器上)。您可以使用 echo “$path” 看到您自己的。它检查 $path 中指定的所有位置并使用第一个位置。 ↩
-
从技术上讲,您可以覆盖并指定 npm 安装二进制文件的位置。 ↩
-
如果你真的想,你可以直接运行 npm exec vitest,简称 npx vitest,./npm_modules/.bin/vitest,或者将 .npm_modules/.bin 添加到你的 path 中。 ↩
-
有些人使用裸 & 在后台运行一项任务,但这在 windows 上不受支持,并且中断一个命令不一定会杀死另一个命令。 ↩