安装 SerialPort


大多数功能都可以在支持 Node.js 的平台上运行和安装,如 x64 的 Mac、Linux 或 Windows 操作系统。借助 npm 在命令行中执行以下命令,即可安装 serialport。

npm install serialport


我们使用 prebuild 来编译 serialport ,大多数情况下不需要进行编译即可使用预编译的二进制包。如果在某些情况下需要进行自行编译二进制文件,可以使用 node gyp 来完成编译。

注意:node gyp 依赖 Python 2.x ,目前不支持 Python 3.x。
如果在 Electron 中使用 serialport 可参考 Electron 使用原生 Node 模块相关章节内容。


Alpine Linux

Alpine is a (very) small distro, but it uses the musl standard library instead of glibc (used by most other Linux distros) so it requires compilation. It's commonly used with Docker. A user has confirmed that Node-Serialport works with alpine-node.

# If you don't have node/npm already, add that first
sudo apk add --no-cache nodejs

# Add the necessary build and runtime dependencies
sudo apk add --no-cache make gcc g++ python linux-headers udev

# Then we can install serialport, forcing it to compile
npm install serialport --build-from-source

# If you're installing as root, you'll also need to use the --unsafe-perm flag


Electron is a framework for creating cross-platform desktop applications. It comes with its own version of the Node.js runtime.

If you require serialport as a dependency for an Electron project, you must compile it for the version of Electron your project's using.

When you first install serialport it will compile against the version of Node.js on your machine, not against the Node.js runtime bundled with Electron.

To recompile serialport (or any native Node.js module) for Electron, you can use electron-rebuild; more info at Electron's README.

  1. npm install --save-dev electron-rebuild
  2. Add electron-rebuild to your project's package.json's install hook
  3. Run npm install

For an example project, check out electron-serialport.


NW.js is an app runtime based on Chromium and node.js.

Like Electron, NW.js also requires compilation against its own specific headers.

To instruct prebuild to build against the correct headers, place a file named .prebuildrc on your package root with the following content:


Where <target_version> is the NW.js version you are building against (for example, 0.26.6).

Illegal Instruction

The pre-compiled binaries assume a fully capable chip. Intel's Galileo 2, for example, lacks a few instruction sets from the ia32 architecture. A few other platforms have similar issues. If you get Illegal Instruction when trying to run Node-Serialport, you'll need to ask npm to rebuild the Serialport binary.

# Will ask npm to build serialport during install time
npm install serialport --build-from-source

# If you have a package that depends on serialport, you can ask npm to rebuild it specifically...
npm rebuild serialport --build-from-source

Mac OS X

Ensure that you have at a minimum the xCode Command Line Tools installed appropriate for your system configuration. If you recently upgraded the OS, it probably removed your installation of Command Line Tools, please verify before submitting a ticket. To compile node-serialport with Node.js 4.x+, you will need to use g++ v4.8 or higher.

Raspberry Pi Linux

Follow the instruction

Raspberry Pi Linux

Follow the instructions for setting up a Raspberry pi for use with Johnny-Five and Raspi IO. These projects use Node Serialport under the hood.

Revision CPU Arm Version
A, A+, B, B+ 32-bit ARM1176JZF-S ARMv6
Compute Module 32-bit ARM1176JZF-S ARMv6
Zero 32-bit ARM1176JZF-S ARMv6
B2 32-bit ARM Cortex-A7 ARMv7
B3 32-bit ARM Cortex-A53 ARMv8

To enable the serial port on Raspbian, you launchraspi-config, then select Interfacing Options, then Serial. You will then be asked two questions:

1.Would you like a login shell to be accessible over serial?
2.Would you like the serial port hardware to be enabled?

You must answer No to question 1 and Yes to question 2. If the login shell is left active, you will experience hangs and or disconnects.

DietPi also has the ability to enable the serial port in dietpi-config; however, it doens't have a way to disable the login shell that we know of.

sudo / root

If you're going to use sudo or root to install Node-Serialport, npm will require you to use the unsafe parameters flag.

sudo npm install serialport --unsafe-perm --build-from-source

Failure to use the flag results in an error like this:

root@rpi3:~# npm install -g serialport
/usr/bin/serialport-list -> /usr/lib/node_modules/serialport/bin/serialport-list.js
/usr/bin/serialport-term -> /usr/lib/node_modules/serialport/bin/serialport-terminal.js

> serialport@6.0.0-beta1 install /Users/wizard/src/node-serialport
> prebuild-install || node-gyp rebuild

prebuild-install info begin Prebuild-install version 2.2.1
prebuild-install info install installing standalone, skipping download.

gyp WARN EACCES user "root" does not have permission to access the dev dir "/root/.node-gyp/6.9.1"
gyp WARN EACCES attempting to reinstall using temporary dev dir "/usr/lib/node_modules/serialport/.node-gyp"
make: Entering directory '/usr/lib/node_modules/serialport/build'
make: *** No rule to make target '../.node-gyp/6.9.1/include/node/common.gypi', needed by 'Makefile'.  Stop.
make: Leaving directory '/usr/lib/node_modules/serialport/build'
gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

Ubuntu/Debian Linux

The best way to install any version of Node.js is to use the NodeSource Node.js binary distributions. Older versions of Ubuntu install Node.js with the wrong version and binary name. If your Node binary is nodejs instead of node, or if your Node version is v0.10.29, then you should follow these instructions.

You'll need the package build-essential to compile serialport. If there's a binary for your platform, you won't need it. Keep rocking!

# Using Ubuntu and Node 6
curl -sL | sudo -E bash -
sudo apt-get install -y nodejs

# Using Debian and Node 6 as root
curl -sL | bash -
apt-get install -y nodejs


Node-Serialport supports Windows 7, 8.1, 10, and 10 IoT. Precompiled binaries are available, but if you want to build it from source you'll need to follow the node-gyp installation instructions. Once you've got things working, you can install Node-Serialport from source with:

npm install serialport --build-from-source

Node-gyp's documentation doesn't mention it, but it sometimes helps to create a C++ project in Visual Studio so that it will install any necessary components not already installed during the past two hours of setup. This will solve some instances of Failed to locate: "CL.exe".

An old issue that you may still run into: when working with multiple Serial Ports you can set the UV_THREADPOOL_SIZE environment variable to be set to 1 + the number of ports you wish to open at a time. Defaults to 4 which supports 3 open ports.

上一篇 下一篇
讨论数量: 0