跳转到内容
Tauri

@tauri-apps/plugin-shell

访问系统外壳。允许您使用默认应用程序 spawning 子进程和管理文件和 URL。

安全

此 API 具有作用域配置,该配置强制您限制可使用的程序和参数。

限制对 open API 的访问

在配置对象中,open: true 表示可以与任何 URL 使用 open API,因为参数将通过 ^((mailto:\w+)|(tel:\w+)|(https?://\w+)).+ 正则表达式进行验证。您可以通过将布尔值更改为字符串来更改该正则表达式,例如 open: ^https://github.com/

限制对 Command API 的访问

插件权限对象有一个 scope 字段,它定义了一个可以使用的一组 CLIs。每个 CLI 是一个配置对象 { name: string, cmd: string, sidecar?: bool, args?: boolean | Arg[] }

  • name: 命令的唯一标识符,传递给 Command.create 函数。如果是 sidecar,则必须是 tauri.conf.json > bundle > externalBin 中定义的值。
  • cmd: 在此配置上执行的程序。如果是 sidecar,则忽略此值。
  • sidecar: 对象是否配置为 sidecar 或系统程序。
  • args: 可传递给程序的参数。默认情况下不允许任何参数。
    • true 意味着允许任何参数列表。
    • false 意味着不允许任何参数。
    • 否则可以配置一个数组。每个项要么是表示固定参数值的字符串,要么是 { validator: string },用于定义验证参数值的正则表达式。

示例作用域配置

CLI: git commit -m "the commit message"

功能

{
"permissions": [
{
"identifier": "shell:allow-execute",
"allow": [
{
"name": "run-git-commit",
"cmd": "git",
"args": ["commit", "-m", { "validator": "\\S+" }]
}
]
}
]
}

用法

import { Command } from '@tauri-apps/plugin-shell'
Command.create('run-git-commit', ['commit', '-m', 'the commit message'])

尝试执行任何不在作用域上配置的程序,会导致由于拒绝访问而导致的 promise 拒绝。

子类

2.0.0

构造函数

new Child()
new Child(pid): Child
参数
参数类型
进程ID数量
返回值

子类

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L301

属性

属性类型描述定义于
pid数量子进程的 pid来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L299

方法

kill()
kill(): Promise<void>

杀死子进程。

返回值

Promise<void>

表示操作成功或失败的山现。

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L336

write()
write(data): Promise<void>

data 写入 stdin

参数
参数类型描述
数据IOPayload | number[]要写入的消息,可以是字符串或字节数组。
返回值

Promise<void>

表示操作成功或失败的山现。

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
const child = await command.spawn();
await child.write('message');
await child.write([0, 1, 2, 3, 4, 5]);

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L322


Command<O>

子进程启动的入口点。它触发 closeerror 事件。

示例

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('node');
command.on('close', data => {
console.log(`command finished with code ${data.code} and signal ${data.signal}`)
});
command.on('error', error => console.error(`command error: "${error}"`));
command.stdout.on('data', line => console.log(`command stdout: "${line}"`));
command.stderr.on('data', line => console.log(`command stderr: "${line}"`));
const child = await command.spawn();
console.log('pid:', child.pid);

2.0.0

扩展

类型参数

类型参数
O extends IOPayload

属性

属性修饰符类型描述定义于
stderr只读EventEmitter<OutputEvents<O>>stderr 的事件发射器。触发 data 事件。来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L384
stdout只读EventEmitter<OutputEvents<O>>stdout 的事件发射器。触发 data 事件。来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L382

方法

addListener()
addListener<N>(eventName, listener): this

等同于 emitter.on(eventName, listener)

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

继承自

EventEmitter.addListener

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L118

execute()
execute(): Promise<ChildProcess<O>>

以子进程的方式执行命令,等待其完成并收集所有输出。

返回值

Promise<ChildProcess<O>>

解析为子进程输出的山现。

示例
import { Command } from '@tauri-apps/plugin-shell';
const output = await Command.create('echo', 'message').execute();
assert(output.code === 0);
assert(output.signal === null);
assert(output.stdout === 'message');
assert(output.stderr === '');

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L530

listenerCount()
listenerCount<N>(eventName): number

返回监听 eventName 事件的监听器数量。

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件名N
返回值

数量

2.0.0

继承自

EventEmitter.listenerCount

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L241

off()
off<N>(eventName, listener): this

从事件eventName的监听器数组中移除所有指定的监听器。返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

继承自

EventEmitter.off

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L186

on()
on<N>(eventName, listener): this

listener函数添加到名为eventName的事件的监听器数组的末尾。不会检查是否已经添加了listener。传递相同组合的eventNamelistener的多个调用将导致listener被多次添加和调用。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

继承自

EventEmitter.on

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L147

once()
once<N>(eventName, listener): this

为名为eventName的事件添加一个一次性listener函数。当eventName被触发下一次时,该监听器被移除然后被调用。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

继承自

EventEmitter.once

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L169

prependListener()
prependListener<N>(eventName, listener): this

listener函数添加到名为eventName的事件的监听器数组的开始位置。不会检查是否已经添加了listener。传递相同组合的eventNamelistener的多个调用将导致listener被多次添加和调用。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

继承自

EventEmitter.prependListener

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L258

prependOnceListener()
prependOnceListener<N>(eventName, listener): this

为名为eventName的事件添加一个一次性listener函数到监听器数组的开始位置。当eventName被触发下一次时,该监听器被移除然后被调用。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

继承自

EventEmitter.prependOnceListener

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L280

removeAllListeners()
removeAllListeners<N>(event?): this

移除所有监听器或指定的事件名的那些监听器。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件?N
返回值

this

2.0.0

继承自

EventEmitter.removeAllListeners

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L206

removeListener()
removeListener<N>(eventName, listener): this

emitter.off(eventName, listener)的别名。

类型参数
类型参数
N extends keyof CommandEvents
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

继承自

EventEmitter.removeListener

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L130

spawn()
spawn(): Promise<Child>

作为子进程执行命令,返回对此进程的句柄。

返回值

Promise<Child>

一个解析为子进程句柄的承诺。

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L479

create()

创建一个执行给定程序的命令。

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();
参数

要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope 中配置。

create(program, args)
static create(program, args?): Command<string>

创建一个执行给定程序的命令。

参数
参数类型
programstring
args?string | string[]
返回值

Command<string>

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();
参数

要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope 中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L406

create(program, args, options)
static create(
program,
args?,
options?): Command<Uint8Array<ArrayBufferLike>>

创建一个执行给定程序的命令。

参数
参数类型
programstring
args?string | string[]
options?SpawnOptions & object
返回值

Command<Uint8Array<ArrayBufferLike>>

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();
参数

要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope 中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L407

create(program, args, options)
static create(
program,
args?,
options?): Command<string>

创建一个执行给定程序的命令。

参数
参数类型
programstring
args?string | string[]
options?SpawnOptions
返回值

Command<string>

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.create('my-app', ['run', 'tauri']);
const output = await command.execute();
参数

要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope 中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L412

sidecar()

创建一个执行给定辅助程序的命令。

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();
参数

要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope 中配置。

sidecar(program, args)
static sidecar(program, args?): Command<string>

创建一个执行给定辅助程序的命令。

参数
参数类型
programstring
args?string | string[]
返回值

Command<string>

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();
参数

要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope 中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L438

sidecar(program, args, options)
static sidecar(
program,
args?,
options?): Command<Uint8Array<ArrayBufferLike>>

创建一个执行给定辅助程序的命令。

参数
参数类型
programstring
args?string | string[]
options?SpawnOptions & object
返回值

Command<Uint8Array<ArrayBufferLike>>

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();
参数

要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope 中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L439

sidecar(program, args, options)
static sidecar(
program,
args?,
options?): Command<string>

创建一个执行给定辅助程序的命令。

参数
参数类型
programstring
args?string | string[]
options?SpawnOptions
返回值

Command<string>

示例
import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('my-sidecar');
const output = await command.execute();
参数

要执行的程序。它必须在 tauri.conf.json > plugins > shell > scope 中配置。

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L444


EventEmitter<E>

2.0.0

由...扩展

类型参数

类型参数
E extends Record<string, any>

构造函数

new EventEmitter()
new EventEmitter<E>(): EventEmitter<E>
返回值

EventEmitter<E>

方法

addListener()
addListener<N>(eventName, listener): this

等同于 emitter.on(eventName, listener)

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L118

listenerCount()
listenerCount<N>(eventName): number

返回监听 eventName 事件的监听器数量。

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件名N
返回值

数量

2.0.0

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L241

off()
off<N>(eventName, listener): this

从事件eventName的监听器数组中移除所有指定的监听器。返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L186

on()
on<N>(eventName, listener): this

listener函数添加到名为eventName的事件的监听器数组的末尾。不会检查是否已经添加了listener。传递相同组合的eventNamelistener的多个调用将导致listener被多次添加和调用。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L147

once()
once<N>(eventName, listener): this

为名为eventName的事件添加一个一次性listener函数。当eventName被触发下一次时,该监听器被移除然后被调用。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L169

prependListener()
prependListener<N>(eventName, listener): this

listener函数添加到名为eventName的事件的监听器数组的开始位置。不会检查是否已经添加了listener。传递相同组合的eventNamelistener的多个调用将导致listener被多次添加和调用。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L258

prependOnceListener()
prependOnceListener<N>(eventName, listener): this

为名为eventName的事件添加一个一次性listener函数到监听器数组的开始位置。当eventName被触发下一次时,该监听器被移除然后被调用。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L280

removeAllListeners()
removeAllListeners<N>(event?): this

移除所有监听器或指定的事件名的那些监听器。

返回对EventEmitter的引用,以便可以进行链式调用。

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件?N
返回值

this

2.0.0

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L206

removeListener()
removeListener<N>(eventName, listener): this

emitter.off(eventName, listener)的别名。

类型参数
类型参数
N extends string | number | symbol
参数
参数类型
事件名N
监听器(arg) => void
返回值

this

2.0.0

来源https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L130

接口

ChildProcess<O>

2.0.0

类型参数

类型参数
O extends IOPayload

属性

属性类型描述定义于
codenull | number进程的退出码。在Unix上,如果进程被信号终止,则为 null来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L94
signalnull | number如果进程被信号终止,表示该信号。来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L96
stderrO进程写入 stderr 的数据。来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L100
stdoutO进程写入 stdout 的数据。来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L98

CommandEvents

属性

属性类型定义于
closeTerminatedPayload来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L345
errorstring来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L346

OutputEvents<O>

类型参数

类型参数
O extends IOPayload

属性

属性类型定义于
dataO来源: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L350

SpawnOptions

2.0.0

属性

属性类型描述定义于
cwd?string当前工作目录。: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L73
encoding?string标准输出/标准错误字符编码 自2.0.0起: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L81
env?Record<string, string>环境变量。设置为 null 以清除进程环境。: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L75

TerminatedPayload

Terminated 命令事件的有效负载。

属性

属性类型描述定义于
codenull | number进程的退出码。在Unix上,如果进程被信号终止,则为 null: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L560
signalnull | number如果进程被信号终止,表示该信号。: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L562

类型别名

IOPayload

type IOPayload: string | Uint8Array;

事件有效负载类型

: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L566

函数

open()

function open(path, openWith?): Promise<void>

使用系统默认应用或通过 openWith 指定打开路径或URL。

必须使用以下其中一个值作为 openWith 的值:firefoxgoogle chromechromiumsafariopenstartxdg-opengiognome-openkde-openwslview

参数

参数类型描述
路径string要打开的路径或URL。此值将与在 tauri.conf.json > plugins > shell > open 定义的字符串正则表达式进行匹配,默认为 `^((mailto:\w+)
openWith?string用于打开文件或URL的应用程序。默认为指定的路径类型的系统默认应用。

返回值

Promise<void>

示例

import { open } from '@tauri-apps/plugin-shell';
// opens the given URL on the default browser:
await open('https://github.com/tauri-apps/tauri');
// opens the given URL using `firefox`:
await open('https://github.com/tauri-apps/tauri', 'firefox');
// opens a file using the default program:
await open('/path/to/file');

2.0.0

: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/shell/guest-js/index.ts#L601


© 2025 Tauri 贡献者。CC-BY / MIT