小林技术之路 https://blog.lintech1024.com/ 且看一名普通程序员, 如何修炼技术, 成为技术大佬 Wed, 11 Feb 2026 00:00:00 GMT https://validator.w3.org/feed/docs/rss2.html https://github.com/jpmonette/feed zh-CN <![CDATA[Playwright 使用教程]]> https://blog.lintech1024.com/playwright-tutorial https://blog.lintech1024.com/playwright-tutorial Wed, 11 Feb 2026 00:00:00 GMT Playwright是微软开源的浏览器自动化工具, 支持多浏览器引擎, 提供Python、JavaScript等多语言API. 它通过真实浏览器渲染页面获取数据, 操作接近真实用户, 在数据采集方面可以有效规避反爬机制. 下面我将介绍如何使用这一工具.

什么是 Playwright?​

  • Web自动化测试工具, 也可以用来作为爬虫工具
  • 通过真实浏览器渲染页面后获取数据, 对比通过 API 调用获取数据的方式速度会慢点, 但是简单粗暴, 接近真实用户浏览网页, 较难被反爬针对

工具对比​

  • Selenium: 基于 Webdriver, 需要中间层转发, 性能较差. 驱动安装麻烦
  • Puppeteer: 谷歌出品, 基于Chrome DevTools Protocol(CDP), 性能高. 针对 Chrome 浏览器, 语言支持Javascript
  • Playwright: 微软出品, Puppeteer 增强版, 接口与 Puppeteer 几乎一样. 社区活跃文档质量高, 容易上手, 支持多浏览器, 支持多语言(Javascript,Python,Java,C#), 自动管理浏览器安装, 支持Docker部署.

前置准备​

test和lib模式​

Playwright 支持两种代码模式, test 和lib 模式, test 模式对于测试方面会更加方便强大, 而我们用于爬虫更适合使用 lib 模式

安装​

安装 Python 库​

pip install playwright

安装浏览器​

playwright install

交互模式(REPL)​

Python 是解释型语言, 它不需要把整个文件代码编译后才能执行, 可以写一行代码执行一行, 这在开发阶段提供了极大的便利

在命令行输入 python 进入交互界面, 然后就可以一行一行输入代码

from playwright.sync_api import sync_playwright
playwright = sync_playwright().start()
browser = playwright.chromium.launch()
page = browser.new_page()
page.goto("https://playwright.dev/")
page.screenshot(path="example.png")
browser.close()
playwright.stop()

同步和异步​

  • Python 异步编程
    • 异步函数需要在 def 前加 async
    • 每次调用异步函数需要在前面加 await
    • main 函数需要放在 asyncio.run() 里执行
  • 可以开发阶段先在交互模式用同步代码边调试边写, 待验证没问题了改成异步代码

上面的代码在异步模式代码如下

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run(playwright: Playwright):
    chromium = playwright.chromium # or "firefox" or "webkit".
    browser = await chromium.launch()
    page = await browser.new_page()
    await page.goto("http://example.com")
    # other actions...
    await browser.close()

async def main():
    async with async_playwright() as playwright:
        await run(playwright)
asyncio.run(main())

with 和 start​

Python 的 with 语句可以自动管理资源的回收, 建议代码使用 with 语句, 交互模式使用 start()

# 用 with
with sync_playwright() as playwright:
    run(playwright)

# 用 start
playwright = sync_playwright().start()
run(playwright)
playwright.stop() # 需要主动调用资源回收

类型注解​

Python 是动态类型语言, 对象的类型在运行时才确定, 在写代码阶段, 编辑器可能因为没有足够的类型信息而无法进行类型补全, 如果把类型注解补上, 编辑器就能知道对象什么类型, 从而进行智能补全

async def run(playwright: Playwright):

Python 异常​

Playwright 有些操作会抛出异常, 在 Python 中异常要用 try ... except 捕获, 不然会程序终止退出

try:
    ...
except Exception as e:   # except Exception as e: 捕获特定异常
    ...
finally:  # 可不需要
   ...

第一个代码​

from playwright.sync_api import sync_playwright
playwright = sync_playwright().start()
browser = playwright.chromium.launch(headless=False)
context = browser.new_context()
page = context.new_page()
page.goto("https://example.com")
page.locator('p').all_inner_texts()
page.locator('a').click()
context.close()
browser.close()
playwright.stop()

Playwright​

根对象, 使用 with 语句不用调用 stop() 方法

# 异步使用 with
async with async_playwright() as playwright

# 同步使用 start()
playwright = sync_playwright().start()
...
playwright.stop()

BrowserType​

对应一个浏览器类型, 通过 Playwright 对象的属性获得

chromium = playwright.chromium

Browser​

  • 对应一个浏览器实例
  • 通过 BrowserType 对象的 launch() 方法创建 Browser 对象
  • launch() 方法可以带上参数, 默认浏览器以无头模式启动, 在开发时可以设置参数为 headless=False 让浏览器可见, 生产爬取时需要去掉
browser = await chromium.launch(headless=False)

记得调用 close() 方法回收资源

await browser.close()

BrowserContext​

context 的设计提供了一种隔离浏览器会话的机制, 不同的 context 不会共享 Cookies 和缓存, Browser 对象提供 new_context() 方法创建 BrowserContext 对象

context = await browser.new_context()

同样需要记得调用 close() 方法回收资源

await context.close()

一个 Browser 对象可以创建多个 BrowserContext 对象

context1 = await browser.new_context()
context2 = await browser.new_context()

Page​

  • 对应一个浏览器标签页
  • Page 对象可以通过 BrowserContext 对象的 new_page() 方法创建, 也可以直接通过 Browser 对象的 new_page() 方法创建(自动在内部创建新的 BrowserContext)

使用 goto() 方法请求URL

page.goto("https://example.com")

有时为了防止代码执行完浏览器直接关闭, 可以使用 pause() 方法暂停页面(需要设置参数headless=False)

await page.pause()

Locator​

Locator 对象代表 Page 被选中的节点元素, Page 对象提供多种方法获取 Locator, 如 get_by_...(), query_selector() 方法, 推荐统一用 locator() 方法

page.locator('#id')    # 根据id选择
page.locator('.class') # 根据class选择
page.locator('h1')     # 根据元素类型选择

选中元素后可以像人工操作一样任意操作, Locator 提供了这些方法

获取文本​

建议用 inner_text() 方法

# 获取所有可见文本
texts = await page.get_by_role("link").all_inner_texts()

# 获取所有文本
texts = await page.get_by_role("link").all_text_contents()

# 获取所有文本(所有子元素拼在一起)
text = await page.get_by_role("link").inner_text()

文本输入 fill()​

await page.get_by_role("textbox").fill("Peter")

鼠标点击 click()​

# 单击
await page.get_by_role("button").click()
# 双击
await page.get_by_role("button").dblclick()

通过 Mouse 对象

await page.mouse.down()
await page.mouse.move(0, 100)
await page.mouse.up()

await page.mouse.wheel(0, 10) # 滚动

下拉框选择 select_option()​

await element.select_option("blue")

# 选中多个
await element.select_option(value=["red", "green", "blue"])

键盘输入 press()​

await page.get_by_text("Submit").press("Enter")

通过 Keyboard 对象

# 输入单个字符
await page.keyboard.press("a")

# 输入多个字符
await page.keyboard.type("Hello")

# 按下某个键
await page.keyboard.down("Shift")

# 放开某个键
await page.keyboard.up("Shift")

文件上传 set_input_files()​

await page.get_by_label("Upload file").set_input_files('myfile.pdf')

拖拽元素 drag_to()​

await page.locator("#item-to-be-dragged").drag_to(page.locator("#item-to-drop-at"))

滚动​

点击滚动按钮自动滚动

await page.get_by_role("button").click()

手动滚动

await page.get_by_text("Footer text").scroll_into_view_if_needed()

用鼠标滚动

await page.get_by_test_id("scrolling-container").hover()
await page.mouse.wheel(0, 10)

用 Javascript 脚本

await page.get_by_test_id("scrolling-container").evaluate("e => e.scrollTop += 100")

元素选择原则​

优先使用 ID 选择器​

img

这里应该用ID选择器, 语法 "#article-title"

类选择器​

img

在没有ID选择器时可退而求其次, 使用类选择器, 语法 ".rich_media_content"

注意

应该使用用于定位元素的类选择器, 而不是用于样式的选择器, 后者非常不稳定, 容易变动

img

".author-avatar" 是个不错的选择器, ".guYtcLAhfKCGOc2ZHrdq" 不太适合

选择父级​

img

如果没有ID选择器和类选择器, 可以先选中父级元素, 通过其获取子元素, 而不是直接选择 span 元素

元素等待​

因为网络请求和节点渲染需要时间, 经常会有元素未加载出来的问题, 这就需要进行等待, 下面是元素等待的要点

  • 任何时候不要用 time.sleep()
  • 操作类的方法不需要提前等待, Playwright 有自动等待和重试的能力. 比如下面一些方法(未完全列举). 这些方法有个 timeout 参数可设置超时时间, 但是建议一般情况不用设置, 用全局超时就行.
    • click()
    • fill()
    • press()
  • 获取元素文本不会自动等待和重试, 这就需要进行等待, 下面是方法对比
    • page.wait_for_timeout() 和 page.wait_for_selector(),已弃用, 不推荐
    • expect(locator).to_be_visible(), expect() 函数多用于测试, 这里不推荐
    • locator.wait_for(), 推荐用这个方法
  • *超时时间不建议在每个方法里设置, 可以通过下面方法设置
    • page.set_default_timeout()
    • browser_context.set_default_timeout()
  • 超时后会抛出 TimeoutError 异常, 记得要用 try 语句捕获

事件​

page.on("dialog", lambda dialog: dialog.accept())

调用 Javascript​

  1. 运行启动脚本
// preload.js
Math.random = () => 42;
await page.add_init_script(path="./preload.js")
  1. 通过 evaluate() 方法运行 Javascript
result = await page.evaluate("([x, y]) => Promise.resolve(x * y)", [7, 8])
print(result) # prints "56"

有用的配置​

Headless​

控制浏览器是否可见, 开发调试时可以设置为 False, 正式不是要设置为 True

browser = await chromium.launch(
    headless=False,
)

防止 navigator.webdriver 检测​

参考文档: https://juejin.cn/post/7520687447237181503#heading-4 当 Chrome 浏览器正在由自动化软件驱动时, 会将 navigator.webdriver 设置为 true, 在正常的浏览器中该值应该为 false.

绕过方法很简单, 启动 Chrome 时加一个 --disable-blink-features=AutomationControlled 开关即可

browser = await chromium.launch(
    args=["--disable-blink-features=AutomationControlled"],
)

防止 viewport 检测​

参考文档: https://juejin.cn/post/7520687447237181503#heading-5 当运行 Puppeteer 时, 它默认使用 800x600 的视口大小, 运行 Playwright 时, 默认使用 1280x720 的视口大小. 这个固定值非常明显, 很容易被检测到, 因为几乎没有哪个正常用户的浏览器会有这样的视口大小

# 在 context 设置
context = await browser.new_context(
    viewport={"width": 1234, "height": 642}, # 只要不是 1280x720 就行
)

# 也可以页面级别设置
page = await browser.new_page(
    viewport={"width": 1234, "height": 642},
)

设置 user-agent​

context = await browser.new_context(
    user_agent="Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1",
)

代理​

可通过 launch() 和 new_context() 方法的参数设置

Cookies​

BrowserContext 有提供 add_cookies() 方法

await browser_context.add_cookies([cookie_object1, cookie_object2])

失败处理​

  1. 用 try 捕获异常, 将错误原因记录日志
  2. 截屏. 因为正式环境用的无头模式, 可能出错了都不知道怎么回事, 截屏可方便排查问题
await page.screenshot(path="example.png")
  1. Playwright 提供 tracing 机制, 可记录这个浏览器操作过程的追踪, 但是可能比较耗性能, 正常情况下不开启
await context.tracing.start(screenshots=True, snapshots=True)
page = await context.new_page()
await page.goto("https://playwright.dev")
await context.tracing.stop(path = "trace.zip")

Docker 部署​

Playwright 支持 Docker 部署, 官方有提供容器镜像, 已经预装好浏览器和相关依赖, 省去我们自己安装浏览器的繁琐.

注意

镜像未安装 Playwright Python 包, 需要我们自己安装依赖

requirements.txt
playwright==1.58.0

可以将整个程序打包成镜像, 下面是 Dockerfile 示例

FROM mcr.microsoft.com/playwright/python:v1.58.0-noble
WORKDIR /app
COPY requirements.txt /app
RUN python -m pip install --upgrade pip && pip install -r requirements.txt 
COPY . /app
CMD ["python", "main.py"]
]]> lintech1024@hotmail.com (小林) 基础教程 网络爬虫 Python <![CDATA[推荐一个PDF转换神器 - Gotenberg]]> https://blog.lintech1024.com/gotenberg https://blog.lintech1024.com/gotenberg Wed, 21 Jan 2026 00:00:00 GMT 发现一个PDF转换神器推荐给大家, 支持转换在线网页、Markdown、Word、Excel等等

Gotenberg 支持通过 Docker 部署为一个服务, 然后通过 curl 请求即可非常方便转换成PDF

安装​

通过 Docker 安装

docker run --rm -p "3000:3000" gotenberg/gotenberg:8

或者用 Docker Compose

services:
  # Your other services.

  gotenberg:
    image: gotenberg/gotenberg:8
    ports:
      - "3000:3000"
     # Or more secure:
     # - "127.0.0.1:3000:3000"

转换​

基于 Chromium​

可转换 URL

curl \
--request POST http://localhost:3000/forms/chromium/convert/url \
--form url=https://my.url \
--form landscape=true \
--form marginTop=1 \
--form marginBottom=1 \
-o my.pdf

基于 LibreOffice​

转换 Word 或 Excel

curl \
--request POST http://localhost:3000/forms/libreoffice/convert \
--form files=@/path/to/file.docx \
--form files=@/path/to/file.xlsx \
--form merge=true \
--form pdfa=PDF/A-1b \
-o my.pdf

基于 PDF Engines​

可合并 PDF

curl \
--request POST http://localhost:3000/forms/pdfengines/merge \
--form files=@/path/to/file1.pdf \
--form files=@/path/to/file2.pdf \
--form files=@/path/to/file3.pdf \
--form files=@/path/to/file4.pdf \
-o my.pdf
]]> lintech1024@hotmail.com (小林) 优秀资源 <![CDATA[Vagrant 使用教程]]> https://blog.lintech1024.com/vagrant https://blog.lintech1024.com/vagrant Tue, 02 Dec 2025 00:00:00 GMT 学习 Kubernetes 等分布式系统时, 硬件资源限制常成为实践瓶颈, 有个方法是用虚拟机模拟机器节点. 本文将介绍如何使用 Vagrant 工具管理虚拟机, 在单机环境中快速构建多节点虚拟机集群

cool-one.png

为什么不用 Docker 搭建集群?​

Docker 容器间共享宿主机内核, 隔离仅限于命名空间, 而虚拟机拥有独立的系统内核, 有自己的网卡, 节点间完全隔离, 用多台虚拟机模拟更接近真实场景

Vagrant 是什么?​

Vagrant 是一个用于构建和管理虚拟机环境的命令行工具, 它通过 Vagrantfile 配置文件, 自动化定义虚拟机的计算资源(CPU、内存)、存储配置、网络拓扑以及操作系统等关键参数, 只要使用相同的 Vagrantfile, 就能创建出完全一致的开发环境, 避免手动操作导致的环境差异

Vagrant 本身不是虚拟机管理程序, 不直接创建或运行虚拟机. 它是一个虚拟化环境的抽象层和自动化工具, 依赖于底层虚拟化平台(如 VirtualBox、VMware、Hyper-V 或 Docker 等)来实际执行虚拟机的创建和管理操作

安装​

安装 Vagrant​

Windows 系统可通过安装包安装 vagrant_2.4.9_windows_amd64.msi, 其他系统参考 Install Vagrant

通过下面命令校验是否成功安装

vagrant --help

安装虚拟化软件​

Vagrant 支持多种虚拟化软件, VirtualBox, Hyper-V, VMware 和 Docker, 个人建议使用 VirtualBox, 这也是 Vagrant 的默认虚拟化软件

可通过官网下载安装包 Download VirtualBox

开始​

创建项目目录并进入​

mkdir learn-vagrant-get-started && cd learn-vagrant-get-started

初始化 Vagrant 环境​

vagrant init hashicorp-education/ubuntu-24-04 --box-version 0.1.0

Vagrant 会在本地创建一个 Vagrantfile 配置文件, 省略了注释后内容如下

Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp-education/ubuntu-24-04"
  config.vm.box_version = "0.1.0"
end

Box​

Vagrant 的 Box 类似于 Docker 的容器镜像, Vagrant 使用配置文件中指定的基础镜像构建虚拟机, 基础镜像通常从官方镜像仓库拉取

上面配置表示, 使用官方镜像仓库上的 hashicorp-education/ubuntu-24-04 镜像, 版本为 0.1.0

官方镜像仓库​

Vagrant 也有类似 Docker Hub 的官方镜像仓库, 地址为 HCP Vagrant Registry

img

启动虚拟机​

vagrant up

如果没有明显报错, 输出完下面日志后就代表虚拟机创建成功

vagrant up 日志

Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'hashicorp-education/ubuntu-24-04'...
==> default: Matching MAC address for NAT networking...
==> default: Checking if box 'hashicorp-education/ubuntu-24-04' version '0.1.0' is up to date...
==> default: Setting the name of the VM: learn-vagrant-get-started_default_1764658229098_38119
==> default: Fixed port collision for 22 => 2222. Now on port 2202.
==> default: Clearing any previously set network interfaces...
==> default: Preparing network interfaces based on configuration...
    default: Adapter 1: nat
==> default: Forwarding ports...
    default: 22 (guest) => 2202 (host) (adapter 1)
==> default: Booting VM...
==> default: Waiting for machine to boot. This may take a few minutes...
    default: SSH address: 127.0.0.1:2202
    default: SSH username: vagrant
    default: SSH auth method: private key
    default: 
    default: Vagrant insecure key detected. Vagrant will automatically replace
    default: this with a newly generated keypair for better security.
    default: 
    default: Inserting generated public key within guest...
    default: Removing insecure key from the guest if it's present...
    default: Key inserted! Disconnecting and reconnecting using new SSH key...
==> default: Machine booted and ready!
==> default: Checking for guest additions in VM...
    default: The guest additions on this VM do not match the installed version of
    default: VirtualBox! In most cases this is fine, but in rare cases it can
    default: prevent things such as shared folders from working properly. If you see
    default: shared folder errors, please make sure the guest additions within the
    default: virtual machine match the version of VirtualBox you have installed on
    default: your host and reload your VM.
    default: 
    default: Guest Additions Version: 7.1.0
    default: VirtualBox Version: 7.2
==> default: Mounting shared folders...
    default: D:/workspace/learn-vagrant-get-started => /vagrant

Vagrant 做了什么?

  • 拉取基础镜像, 通常会从官方镜像仓库拉取
  • 使用虚拟化软件创建虚拟机, 无特殊配置的话默认使用 VirtualBox
  • 网络配置, 配置 NAT 网络使虚拟机可访问外部网络
  • 开启 SSH 服务并将虚拟机的 22 端口转发到宿主机, 使宿主机可以通过 SSH 连上虚拟机
  • 生成 SSH 密钥对并将公钥注入虚拟机
  • 挂载共享文件夹, 将项目目录映射到虚拟机的 /vagrant 目录

打开 VirtualBox 软件可以发现 Vagrant 成功创建了新的虚拟机

img

访问虚拟机​

因为 Vagrant 已为虚拟机开启 SSH 服务并且将公钥注入虚拟机, 所以宿主机可通过 SSH 连接免密访问虚拟机, 通过下面命令即可连上虚拟机

vagrant ssh

在虚拟机内尝试运行命令

vagrant@vagrant-ubuntu:~$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 24.04.1 LTS
Release:        24.04
Codename:       noble

从虚拟机返回宿主机可运行下面命令

logout

休眠虚拟机​

vagrant suspend

img

唤醒虚拟机​

vagrant resume

img

关闭虚拟机​

vagrant halt

img

销毁虚拟机​

vagrant destroy
注意

销毁虚拟机后并不会删除拉取的镜像文件, 如果需要删除镜像需要执行下面命令

vagrant box remove hashicorp-education/ubuntu-24-04

网络​

网络配置      Mode      VM→Host  VM←Host  VM1↔VM2VM→Net/LANVM←Net/LAN
private_networkHost-only✅✅✅❌❌
private_network + virtualbox__intnetInternal❌❌✅❌❌
public_networkBridged✅✅✅✅✅
forwarded_portNAT✅Port forward❌✅Port forward
❌NAT Network✅Port forward✅✅Port forward

Forwarded Port​

Vagrant 的 Forwarded Port 网络模式对应 VirtualBox 的 NAT 网络模式, 这种模式下

  • 虚拟机可以访问外部网络
  • 外部网络无法访问虚拟机
  • 虚拟机之间不互通

在 VirtualBox 中 NAT 网络模式可选开放端口映射让外部网络访问虚拟机, 而在 Vagrant 中 Forwarded Port 网络模式的端口映射是必选项

Vagrant 启动虚拟机时默认会开启 Forwarded Port 网络模式, 并且将虚拟机的 22 端口映射到宿主机, 这样保证宿主机可以通过 vagrant ssh 命令连接到虚拟机

img

在 VirtualBox 的管理器中可以看到 Vagrant 启动的虚拟机中默认有一张 NAT 网卡, 并且有条名称为 ssh 的端口转发规则, 将虚拟机的 22 端口映射到宿主机的 2222 端口

Forwarded Port 网络模式配置

config.vm.network "forwarded_port", guest: 80, host: 8080

如果希望除了宿主机的其他外网无法访问虚拟机

config.vm.network "forwarded_port", guest: 81, host: 8081, host_ip: "127.0.0.1"

可以发现在同块 NAT 网卡上增加了两条端口转发规则

img

Forwarded Port 网络模式会给虚拟机分配 10.0.2.15 地址, 并且可通过 10.0.2.2 地址直接访问宿主机

img

Private Network​

Vagrant 的 Private Network 网络模式对应 VirtualBox 的 Host-only 网络模式, 这种模式下

  • 同一宿主机上的虚拟机之间可互相访问
  • 虚拟机与宿主机之间可相互访问
  • 其他外部网络无法访问该私有网络

Private Network 网络模式可配置静态 IP 或动态 IP

静态 IP​

config.vm.network "private_network", ip: "192.168.50.4"

可以看到虚拟机多了一张 Host-Only 网络模式的网卡

img

在宿主机可以看到 VirtualBox 创建的虚拟网卡, IP 地址跟虚拟机设置的 IP 在同个网段

img

在虚拟机查看 IP 可以发现正是我们说配置的静态 IP

img

动态 IP​

config.vm.network "private_network", type: "dhcp"

Internal 网络​

当配置 virtualbox__intnet 参数时, Private Network 则对应 VirtualBox 的 Internal 网络模式, 这种模式下

  • 虚拟机之间可相互通信
  • 虚拟机和宿主机以及外部网络不互通
config.vm.network "private_network", ip: "192.168.50.4",
  virtualbox__intnet: "mynetwork"
注意

virtualbox__intnet 有两条下划线, 要求网络名称相同的虚拟机才可相互通信

可以看到虚拟机的网卡变成了 Internal 网络模式, 并且名称正是我们所设置的 mynetwork

img

Public Network​

Vagrant 的 Public Network 网络模式对应 VirtualBox 的桥接(Bridged)网络模式, 这种模式下

  • 虚拟机相当于局域网的一台真实机器, 可跟局域网内的任意机器互通
  • 会消耗局域网一个 IP 地址

静态 IP​

config.vm.network "public_network", ip: "192.168.0.17"

Public Network 网络模式会直接使用宿主机的网卡, 所以在启动虚拟机后需要你选择一张网卡

img

可以看到虚拟机使用了桥接模式, 名称正是我们选择的网卡名称

img

注意

设置静态 IP 时要处于局域网的网段, 否则外部网络无法访问虚拟机

img

动态 IP​

如下配置即为设置动态 IP, 局域网会自动分配一个 IP 地址给我们

config.vm.network "public_network"

CPU和内存​

我们在使用虚拟机时经常对 CPU 和内存有要求, 可通过下面配置设置

config.vm.provider "virtualbox" do |v|
  v.memory = 1024
  v.cpus = 2
end
提示

内存的单位是 MB, 不进行设置虚拟机默认为1个CPU和2048MB内存

多节点​

多台机器通过 config.vm.define 方法在配置文件中定义

# 全局公共配置
config.vm.box = "hashicorp-education/ubuntu-24-04"
config.vm.box_version = "0.1.0"

config.vm.define "web"
config.vm.define "db"

多节点命令使用变化

命令说明
vagrant up默认启动所有定义的机器
vagrant up web仅启动名为"web"的机器
vagrant ssh db连接到名为"db"的机器(必须指定机器名)
$ vagrant ssh
This command requires a specific VM name to target in a multi-VM environment.
$ vagrant ssh db
Welcome to Ubuntu 24.04.1 LTS (GNU/Linux 6.8.0-51-generic x86_64)

可通过 primary 参数设置主机器, vagant ssh 可省略机器名, 默认连到主机器上

config.vm.define "web", primary: true
config.vm.define "db"

一主双从节点​

下面我们将配置一个一主双从节点, 每个节点设置各自的主机名、CPU和内存、私有静态IP

Vagrant.configure("2") do |config|

  config.vm.box = "hashicorp-education/ubuntu-24-04"
  config.vm.box_version = "0.1.0"

  config.vm.define "master", primary: true do |master|
    master.vm.hostname = "master"
    master.vm.network "private_network", ip: "192.168.50.10"
    master.vm.provider "virtualbox" do |vb|
      vb.name = "vagrant-master"
      vb.memory = "2048"
      vb.cpus = 2
    end
  end

  config.vm.define "worker1" do |worker1|
    worker1.vm.hostname = "worker1"
    worker1.vm.network "private_network", ip: "192.168.50.11"
    worker1.vm.provider "virtualbox" do |vb|
      vb.name = "vagrant-worker1"
      vb.memory = "1024"
      vb.cpus = 1
    end
  end

  config.vm.define "worker2" do |worker2|
    worker2.vm.hostname = "worker2"
    worker2.vm.network "private_network", ip: "192.168.50.12"
    worker2.vm.provider "virtualbox" do |vb|
      vb.name = "vagrant-worker2"
      vb.memory = "1024"
      vb.cpus = 1
    end
  end
end

成功启动了三台虚拟机

img

使用变量和each简化配置​

将每个节点的专有配置提取到 NODES 变量中, 然后用 each 语法定义每台机器

NODES = {
  'master' => {
    ip: '192.168.50.10',
    cpus: 2,
    memory: 2048,
  },
  'worker1' => {
    ip: '192.168.50.11',
    cpus: 1,
    memory: 1024,
  },
  'worker2' => {
    ip: '192.168.50.12',
    cpus: 1,
    memory: 1024,
  },
}

Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp-education/ubuntu-24-04"
  config.vm.box_version = "0.1.0"

  NODES.each do |name, cfg|
    config.vm.define name do |node|
      node.vm.hostname = name
      node.vm.network "private_network", ip: cfg[:ip]
      node.vm.provider "virtualbox" do |vb|
        vb.name = "vagrant-#{name}"
        vb.cpus = cfg[:cpus]
        vb.memory = cfg[:memory]
      end
    end
  end
end

参考​

]]> lintech1024@hotmail.com (小林) 基础教程 虚拟机 <![CDATA[nginx 实战配置]]> https://blog.lintech1024.com/nginx-conf https://blog.lintech1024.com/nginx-conf Thu, 25 Sep 2025 00:00:00 GMT 本文详解 nginx 核心配置结构，涵盖简单指令、块指令与context作用域层级。重点解析worker_processes、include等核心模块指令，以及静态资源服务、SPA部署、反向代理和负载均衡等实战配置

jetpack.png

示例​

nginx.conf
user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /run/nginx.pid;


events {
    worker_connections  1024;
}


http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    include /etc/nginx/conf.d/*.conf;
}

配置文件结构​

nginx 的配置文件由指令(directives)组成, 分为简单指令(simple directives)和块指令(block directives)

简单指令​

简单指令由指令名称、参数和末尾分号 ; 组成, 名称和参数用空格分隔.

例如下面指令属于简单指令

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /run/nginx.pid;

块指令​

块指令使用大括号 {} 包裹其他指令, 并且不用分号结尾, 这点跟 C 语言有点像

下面指令中 events、http 都属于块指令

events {
    worker_connections  1024;
}


http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    include /etc/nginx/conf.d/*.conf;
}

context​

nginx 的一个块指令内部可以形成一个作用域, 称为 context

main context​

没有被任何块指令包裹, 位于最外层的作用域称为 main context

示例

# main context

http {
    # http context
    server {
        # server context
        location {
            # location context
        }
    }
}

模块​

nginx 由模块组成, 每个模块有对应的指令用于配置模块的功能

nginx 内置以下核心模块, 用于配置 HTTP、邮件、TCP/UDP 服务

还有其他扩展模块, 详细列表可参考官方文档 Modules reference

core module​

ngx_core_module 是 nginx 最核心的一个模块, 包含 nginx 最基础的指令, 用于配置 nginx 的全局参数

基础配置指令

  • user - 定义 worker 进程运行的用户和组
  • worker_processes - 设置 worker 进程数量(可设为具体数值或 auto)
  • error_log - 配置错误日志文件路径和日志级别
  • pid - 指定存储主进程 PID 的文件路径
  • include - 包含其他配置文件或匹配特定掩码的文件
  • env - 保留、修改或创建环境变量
  • daemon - 确定 Nginx 是否以守护进程方式运行

进程管理指令

  • master_process - 控制是否启动 worker 进程
  • worker_cpu_affinity - 将 worker 进程绑定到特定 CPU 核心
  • worker_priority - 设置 worker 进程的调度优先级
  • worker_rlimit_core - 设置 core 文件大小限制
  • worker_rlimit_nofile - 设置 worker 进程可打开文件描述符数量限制
  • worker_shutdown_timeout - 配置 worker 进程优雅关闭的超时时间
  • working_directory - 定义 worker 进程的工作目录

高级功能指令

  • load_module - 加载动态模块(.so 文件)
  • thread_pool - 定义用于多线程读取和发送文件的线程池
  • pcre_jit - 启用或禁用正则表达式的"即时编译"功能
  • timer_resolution - 降低 worker 进程中的计时器精度
  • lock_file - 指定锁文件前缀(用于实现 accept_mutex 等功能)
  • ssl_engine - 定义硬件 SSL 加速器名称
  • ssl_object_cache_inheritable - 配置 SSL 对象在配置重载时是否继承

调试相关指令

  • debug_points - 用于内部错误检测时创建 core 文件或停止进程
  • debug_connection - 为特定客户端连接启用调试日志

include​

需要特别介绍一下 include 指令, 它允许将配置拆分为多个文件,实现配置的模块化管理

基础语法

include file | mask;
  • file: 单个配置文件的绝对/相对路径(如 mime.types)
  • mask: 支持通配符的文件匹配模式(如 conf.d/*.conf)
  • include 指令可以在任何上下文(context)中使用

下面是基于 include 指令进行模块化管理的最佳实践

标准目录结构

/etc/nginx/
├── nginx.conf                # 主配置
├── conf.d/                   # 通用配置
│   ├── gzip.conf
│   └── security.conf
├── sites-available/          # 所有站点配置
│   ├── example.com.conf
│   └── api.example.com.conf
└── sites-enabled/            # 启用的站点(软链接到 sites-available)
    └── example.com.conf → ../sites-available/example.com.conf
nginx.conf
http {
    include       mime.types;
    include       conf.d/*.conf;
    include       sites-enabled/*.conf;
}

HTTP module​

HTTP 的核心模块为 ngx_http_core_module

最简配置

nginx.conf
events {}

http {
    server {
        location / {}
    }
}

配置说明

  • http
    所有 HTTP/HTTPS 服务相关配置必须置于 http 块内. 该块作为核心配置层级, 用于定义全局 HTTP 规则(如 MIME 类型、默认内容类型等)
  • server
    定义虚拟主机(Virtual Host), 用于处理特定域名或端口的请求. 当前配置中省略了 listen 和 server_name 指令, 因此将采用以下默认值:
    • listen: 默认监听 80 端口(HTTP 标准端口)
    • server_name: 默认为空字符串, 可匹配所有未明确指定的域名(即通过 IP 地址或任意域名访问的请求)
  • location
    定义 URI 路径匹配规则, 然后返回块内的文件给到请求, 其中 / 表示匹配所有请求路径. 当前配置中:
    • root: 未显式配置时, 默认路径为 html
    • index: 未指定时, 默认索引文件为 index.html

上面配置的实际效果

  • 用户访问 http://ip:80/index.html(可省略为 http://ip), 返回 html/index.html 文件内容

添加页面

mkdir html && echo "Hello, world!" > html/index.html

访问页面

img

完整的配置如下

http {
    server {
        listen 80;
        server_name "";
        location / {
            root html;
            index index.html;
        }
    }
}

静态资源服务​

nginx 可作为静态资源服务, 配置如下

server {
    location / {
        root /data/www;
    }

    location /images/ {
        root /data;
    }

    # 匹配 .gif .jpg .png 扩展名结尾
    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}

单页面应用​

单页面应用(如 React/Vue/Angular)使用前端路由, 所有路径(如 /about、/dashboard)均由前端 JavaScript 处理, 服务器上不存在对应物理路径

默认配置下, 当用户直接访问 /about 时, nginx 会尝试查找服务器上的 /about 目录或文件, 由于文件不存在会返回 404 错误

配置单页面应用需要使用 try_files 指令, 该指令会在找不到文件时返回一个兜底路径, 这样就能将找不到静态资源的请求都返回到 index.html 页面, 交由前端路由处理

server {
    location / {
        root html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}

反向代理​

可以使用 proxy_pass 指令将请求代理到后端服务

server {
    location /api {
        proxy_pass http://localhost:8080/;
    }
}

负载均衡​

负载均衡可以将请求代理到多个后端实例, 实现服务的高可用

nginx 使用 uptream 指令实现负载均衡, 通过定义后端服务器组实现流量分发

http {
    upstream myapp1 {
        server srv1.example.com;
        server srv2.example.com;
        server srv3.example.com;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://myapp1; # 指向upstream定义的组
        }
    }
}

nginx 负载均衡支持三种算法, 包括

  • 轮询(round-robin): 依次将请求分配给每个服务器, 支持按权重比例分配请求, nginx 默认使用轮询算法
  • 最少连接(least-connected): 将请求分配给当前活跃连接数最少的服务器
  • IP哈希(ip-hash): 根据客户端 IP 计算哈希值, 固定分配到特定服务器
配置最少连接算法​
    upstream myapp1 {
        least_conn;
        server srv1.example.com;
        server srv2.example.com;
        server srv3.example.com;
    }
配置 IP 哈希算法​
upstream myapp1 {
    ip_hash;
    server srv1.example.com;
    server srv2.example.com;
    server srv3.example.com;
}
配置加权轮询​
    upstream myapp1 {
        server srv1.example.com weight=3;
        server srv2.example.com;
        server srv3.example.com;
    }

nginx 自带健康检查机制, 如果某个服务实例不可用, nginx 会将其标记为不可用, 并在一段时间内避免将后续的传入请求分发至该服务器

SSL module​

nginx 的 SSL 加密由 ngx_http_ssl_module 模块提供

server {
    listen              443 ssl;
    server_name         www.example.com;
    ssl_certificate     www.example.com.crt;
    ssl_certificate_key www.example.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;
    ...
}

为确保所有流量都通过HTTPS, 应设置 HTTP 到 HTTPS 的重定向

server {
    listen 80;
    server_name default_server;
    return 301 https://$host$request_uri;
}

参考​

]]> lintech1024@hotmail.com (小林) 快速入门 nginx <![CDATA[直观感受 html lang 作用, 写错这个直接影响网站搜索流量]]> https://blog.lintech1024.com/html-lang https://blog.lintech1024.com/html-lang Sat, 13 Sep 2025 00:00:00 GMT 以前学习 HTML 时只知道 html lang 是标记网页语言的, 具体有什么作用不清楚, 对这一块也不太注意, 随便填个值就算了, 没想到这一小小的细节竟会影响网站搜索流量, 注重站点 SEO 的千万别搞错了

witch-old.png

故事背景​

偶然机会想搜索一下自己文章的 Google 排名, 全语言排在第3页的第2行

img

切换到中文页面, 翻到第3行了竟不见自己文章踪迹

img

排查了一下原因, 没想到 Google 竟很死板的根据页面的 html lang 值过滤搜索结果

简体中文的值为 zh-CN, 而我的博客错误设置成了 zh, 这就导致用中文过滤永远无法搜索到我的文章

img

解决​

知道问题就好办了, 我的博客使用 docusaurus 搭建, 直接修改配置即可

找到 htmllang 改成 zh-CN

img

查看页面, 发现已经改过来了

img

重新部署上去, 静待搜索爬虫重新抓取, 后续看能不能搜索到吧

总结​

html lang 主要影响的是搜索引擎, 搜索引擎会根据这个值判断页面语言, 作为语言过滤条件.

简体中文的 html lang 值是 zh-CN, 千万不要搞错了

提示

其实简体中文的更标准写法是 zh-Hans 或 zh-Hans-CN, 由于历史原因 zh-CN 使用得更多

]]> lintech1024@hotmail.com (小林) 博客技术 前端 <![CDATA[使用 MarkItDown 实现一个文档转 Markdown 服务]]> https://blog.lintech1024.com/markitdown-project https://blog.lintech1024.com/markitdown-project Wed, 10 Sep 2025 10:00:00 GMT MarkItDown 是一个微软开源的 Python 工具, 用于将多种文件格式转换为 Markdown 格式. 本文将介绍如何使用 MarkItDown, 最后用 MarkItDown 实现一个文档转 Markdown 服务

witch-broom.png

前置条件​

安装​

全量依赖安装

pip install 'markitdown[all]

可选依赖安装

pip install 'markitdown[pdf, docx, pptx]'

可选的依赖列表如下:

  • [all] 安装所有可选依赖项
  • [pptx] 安装 PPT 文件的依赖项
  • [docx] 安装 Word 文件的依赖项
  • [xlsx] 安装 Excel 文件的依赖项
  • [xls] 安装旧版 Excel 文件的依赖项
  • [pdf] 安装 PDF 文件的依赖项
  • [outlook] 安装 Outlook 邮件的依赖项
  • [az-doc-intel] 安装 Azure Document Intelligence 的依赖项
  • [audio-transcription] 安装 wav 和 mp3 文件音频转录的依赖项
  • [youtube-transcription] 安装获取 YouTube 视频转录的依赖项

依赖​

ffmpeg​

转换 PDF 时需要依赖 ffmpeg, 这在官方文档并没有提到

Ubuntu 安装 ffmpeg

apt install -y ffmpeg

exiftool​

转换图片需要依赖 exiftool

直接用 Ubuntu 包管理安装的 exiftool 可能有版本太低存在安全漏洞的问题, 需要源码编译高版本

使用 MarkItDown 图片转 Makrdown 的效果并不好, 只能得到类似 "ImageSize: 931x895" 这样的文本, 需要借助大模型的能力才能识别图片内容, 我尝试了用阿里千问的 qwen-vl-max 模型集成, 确实能够正确转换为 Markdown, 但是这样的话还不如直接就用大模型识别, 感觉有点鸡肋

插件​

MarkItDown 支持第三方插件, 感觉功能不太成熟就不多介绍了, 想了解的可以参考官方文档: MarkItDown Plugins

使用​

命令行​

markitdown path-to-file.pdf > document.md

可以使用 -o 参数指定输出文件

markitdown path-to-file.pdf -o document.md

或者使用 Linux 管道符

cat path-to-file.pdf | markitdown

Python API​

基本使用​

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.text_content)

集成大模型​

我使用阿里千问的 qwen-vl-max 模型

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI(base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", api_key="sk-xxx")
md = MarkItDown(llm_client=client, llm_model="qwen-vl-max", llm_prompt="识别图片中的内容, 直接返回原始内容, 不要任何多余处理, 不要返回任何多余的文本")
result = md.convert("a.jpg")
print(result.text_content)

Docker​

MarkItDown 官方并没有提供构建好的 Docker 镜像, 需要自己下载源码构建

博主自己构建了一个镜像, 可以直接使用

docker run --rm -i linrepo/markitdown < ~/your-file.pdf > output.md

封装成服务​

使用 FastAPI 框架将 MarkItDown 封装成一个服务

源码已开源到 GitHub: lintech1024/markitdown-server

开发环境准备​

用 Dev Container 启动开发环境

配置文件

.devcontainer/devcontainer.json
{
    "name": "markitdown-server",
    "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
    "customizations": {
        "vscode": {
            "settings": {
                "window.newWindowProfile": "Default", // 新窗口使用的配置文件, 只能在"默认配置文件"中设置
                "files.autoSave": "afterDelay", // 自动保存文件
                "editor.formatOnSave": true, // 保存时自动格式化
                "files.simpleDialog.enable": true, // 简单对话框, ctrl+n 新建文件时不再弹出对话框
                "editor.insertSpaces": true, // 使用空格代替制表符
                "editor.tabSize": 4, // 缩进空格数
                "editor.autoClosingDelete": "always", // 删除左括号时总是自动删除右括号
                "editor.minimap.autohide": "mouseover", // 鼠标不在缩略图上时隐藏缩略图, 鼠标在缩略图上时显示缩略图
                "terminal.integrated.cursorStyle": "underline", // 终端光标样式使用下划线
                "explorer.confirmDelete": false, // 删除文件时不再弹出确认对话框
                "explorer.confirmDragAndDrop": false, // 拖放移动文件或文件夹时不再弹出确认对话框
                "vsicons.dontShowNewVersionMessage": true, // 不显示新版本消息
                "workbench.iconTheme": "vscode-icons" // 使用 vscode-icons 图标主题
            },
            "extensions": [
                "mhutchie.git-graph", // Git 图形化视图
                "eamodio.gitlens", // Git 增强工具, 主要为了能显示代码作者
				"ms-python.vscode-pylance", // Python 语言支持
                "vscode-icons-team.vscode-icons", // VSCode 图标主题
                "github.copilot", // GitHub Copilot, AI 代码补全
                "github.copilot-chat" // GitHub Copilot Chat, AI 聊天助手
            ]
        }
    },
    "containerEnv": {
        "PIP_INDEX_URL": "https://mirrors.aliyun.com/pypi/simple/",
        "PIP_TRUSTED_HOST": "mirrors.aliyun.com"
    },
    "postCreateCommand": "bash scripts/install.sh",
    "postStartCommand": "uvicorn main:app --reload",
	"forwardPorts": [8000]
}
scripts/install.sh
# 使用阿里源
sudo sed -i "s@deb.debian.org@mirrors.aliyun.com@g" /etc/apt/sources.list

# 更新 apt 并安装 ffmpeg
sudo apt update && sudo apt upgrade -y
sudo apt install -y ffmpeg
# sudo apt install -y exiftool

# 更新 pip 并安装 markitdown
pip install -U pip && pip install markitdown[all]

# 安装 fastapi
pip install fastapi uvicorn[standard] python-multipart

API 接口​

上传文件并让 MarkItDown 转换

main.py
@app.post("/uploadfile/")
async def convert_file(file: UploadFile):
    try:
        contents = await file.read()
        converter = MarkItDown()
        result = converter.convert(io.BytesIO(contents))
        return Response(content=result.text_content)
    except Exception as e:
        print(f"Error during conversion: {str(e)}")
        raise HTTPException(status_code=500, detail=f"转换失败: {str(e)}")

MarkItDown 支持直接转换网页, 再编写一个转网页接口

main.py
@app.post("/convertPage/")
async def convert_page(url: str):
    try:
        converter = MarkItDown()
        result = converter.convert(url)
        return Response(content=result.text_content)
    except Exception as e:
        print(f"Error during conversion: {str(e)}")
        raise HTTPException(status_code=500, detail=f"转换失败: {str(e)}")

前端页面​

直接让AI帮我们写前端页面, 效果是真不错 👍

页面代码

static/index.html
<!DOCTYPE html>
<html lang="zh-CN">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>文档转Markdown</title>
    <style>
        * {
            box-sizing: border-box;
            margin: 0;
            padding: 0;
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
        }

        body {
            background-color: #f5f7fa;
            color: #333;
            line-height: 1.6;
            padding: 20px;
            max-width: 800px;
            margin: 0 auto;
        }

        .container {
            background: white;
            border-radius: 10px;
            box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
            padding: 30px;
            margin-top: 20px;
        }

        header {
            text-align: center;
            margin-bottom: 30px;
        }

        h1 {
            color: #2c3e50;
            margin-bottom: 10px;
        }

        .description {
            color: #7f8c8d;
            max-width: 600px;
            margin: 0 auto;
        }

        .url-converter {
            margin-top: 30px;
            padding-top: 20px;
            border-top: 1px solid #eee;
        }

        .url-converter h2 {
            text-align: center;
            margin-bottom: 10px;
            color: #2c3e50;
        }

        .url-input-group {
            display: flex;
            gap: 10px;
            margin-top: 10px;
        }

        .url-input {
            flex: 1;
            padding: 12px 15px;
            border: 1px solid #ddd;
            border-radius: 5px;
            font-size: 16px;
            outline: none;
            transition: border-color 0.3s;
        }

        .url-input:focus {
            border-color: #3498db;
        }

        .upload-area {
            border: 2px dashed #3498db;
            border-radius: 8px;
            padding: 40px 20px;
            text-align: center;
            background-color: #f8f9fa;
            transition: all 0.3s ease;
            cursor: pointer;
            margin-bottom: 20px;
        }

        .upload-area:hover,
        .upload-area.dragover {
            background-color: #e3f2fd;
            border-color: #2980b9;
        }

        .upload-icon {
            font-size: 48px;
            color: #3498db;
            margin-bottom: 15px;
        }

        .upload-text {
            font-size: 18px;
            color: #2c3e50;
            margin-bottom: 10px;
        }

        .upload-hint {
            color: #7f8c8d;
            font-size: 14px;
        }

        .formats-list {
            display: flex;
            flex-wrap: wrap;
            justify-content: center;
            gap: 10px;
            margin-top: 15px;
        }

        .format-tag {
            background-color: #e1f5fe;
            color: #0288d1;
            padding: 3px 10px;
            border-radius: 15px;
            font-size: 12px;
            font-weight: bold;
        }

        .file-input {
            display: none;
        }

        .btn {
            background-color: #3498db;
            color: white;
            border: none;
            padding: 12px 24px;
            border-radius: 5px;
            font-size: 16px;
            cursor: pointer;
            transition: background-color 0.3s;
            display: inline-block;
            margin-top: 10px;
        }

        .btn:hover {
            background-color: #2980b9;
        }

        .btn:disabled {
            background-color: #95a5a6;
            cursor: not-allowed;
        }

        .status {
            margin-top: 20px;
            padding: 15px;
            border-radius: 5px;
            display: none;
        }

        .status.processing {
            background-color: #e3f2fd;
            color: #1976d2;
            display: block;
        }

        .status.success {
            background-color: #d4edda;
            color: #155724;
            display: block;
        }

        .status.error {
            background-color: #f8d7da;
            color: #721c24;
            display: none;
        }

        .progress-container {
            width: 100%;
            height: 10px;
            background-color: #e9ecef;
            border-radius: 5px;
            margin-top: 15px;
            overflow: hidden;
            display: none;
        }

        .progress-bar {
            height: 100%;
            background-color: #28a745;
            width: 0%;
            transition: width 0.3s;
        }

        .file-info {
            margin-top: 15px;
            padding: 10px;
            background-color: #f8f9fa;
            border-radius: 5px;
            display: none;
        }

        .features {
            display: flex;
            justify-content: space-between;
            margin-top: 30px;
            flex-wrap: wrap;
            gap: 20px;
        }

        .feature {
            flex: 1;
            min-width: 250px;
            padding: 15px;
            text-align: center;
            background: #f8f9fa;
            border-radius: 8px;
            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
        }

        .feature-icon {
            font-size: 28px;
            color: #3498db;
            margin-bottom: 10px;
        }

        .spinner {
            display: inline-block;
            width: 20px;
            height: 20px;
            border: 3px solid rgba(0, 0, 0, 0.1);
            border-radius: 50%;
            border-top-color: #3498db;
            animation: spin 1s ease-in-out infinite;
            margin-right: 8px;
            vertical-align: middle;
        }

        @keyframes spin {
            to {
                transform: rotate(360deg);
            }
        }

        @media (max-width: 600px) {
            .container {
                padding: 20px 15px;
            }

            .upload-area {
                padding: 30px 15px;
            }

            .features {
                flex-direction: column;
            }

            .feature {
                min-width: 100%;
            }

            .url-input-group {
                flex-direction: column;
            }
        }
    </style>
</head>

<body>
    <div class="container">
        <header>
            <h1>文档转Markdown</h1>
            <p class="description">上传PDF、Office文档等文件, 一键转换为结构完整的Markdown格式, 支持拖拽上传</p>
        </header>

        <div class="upload-area" id="dropZone">
            <div class="upload-icon">📄</div>
            <div class="upload-text">点击选择文件或拖拽到此处</div>
            <div class="upload-hint">支持多种格式, 最大支持50MB</div>
            <div class="formats-list">
                <span class="format-tag">PDF</span>
                <span class="format-tag">Word</span>
                <span class="format-tag">Excel</span>
                <span class="format-tag">PPT</span>
                <span class="format-tag">TXT</span>
                <span class="format-tag">HTML</span>
            </div>
            <input type="file" class="file-input" id="fileInput" accept=".pdf,.docx,.xlsx,.xls,.pptx,.txt,.html" />
            <button class="btn" id="browseBtn">选择文件</button>
        </div>

        <div class="file-info" id="fileInfo">
            <div>已选择: <span id="fileName"></span></div>
            <div>大小: <span id="fileSize"></span></div>
        </div>

        <!-- URL转换区域移动到文档转换区域下方 -->
        <div class="url-converter">
            <h2>网页转Markdown</h2>
            <p class="description">输入网页URL地址, 一键转换为Markdown格式</p>
            <div class="url-input-group">
                <input type="url" class="url-input" id="urlInput" placeholder="https://example.com" required>
                <button class="btn" id="convertUrlBtn">转换网页</button>
            </div>
        </div>

        <div class="status processing" id="processingStatus" style="display: none;">
            <span class="spinner"></span>正在转换文档，请稍候...
        </div>

        <div class="progress-container" id="progressContainer">
            <div class="progress-bar" id="progressBar"></div>
        </div>

        <div class="status success" id="successStatus" style="display: none;">
            转换成功！正在下载...
        </div>

        <div class="status error" id="errorStatus" style="display: none;">
            转换失败：未知错误
        </div>

        <!-- 更新features区域，强调支持转换页面 -->
        <div class="features">
            <div class="feature">
                <div class="feature-icon">🔄</div>
                <h3>智能转换</h3>
                <p>保留文档结构, 准确转换为Markdown格式</p>
            </div>
            <div class="feature">
                <div class="feature-icon">🌐</div>
                <h3>网页与文档转换</h3>
                <p>支持网页和文档一键转换为Markdown格式</p>
            </div>
        </div>
    </div>

    <script>
        document.addEventListener('DOMContentLoaded', function () {
            // 原有文件上传相关元素
            const dropZone = document.getElementById('dropZone');
            const fileInput = document.getElementById('fileInput');
            const browseBtn = document.getElementById('browseBtn');
            const fileInfo = document.getElementById('fileInfo');
            const fileName = document.getElementById('fileName');
            const fileSize = document.getElementById('fileSize');

            // 新增URL转换相关元素
            const urlInput = document.getElementById('urlInput');
            const convertUrlBtn = document.getElementById('convertUrlBtn');

            // 状态元素（共用）
            const progressContainer = document.getElementById('progressContainer');
            const progressBar = document.getElementById('progressBar');
            const processingStatus = document.getElementById('processingStatus');
            const successStatus = document.getElementById('successStatus');
            const errorStatus = document.getElementById('errorStatus');

            // 确保所有状态默认隐藏
            processingStatus.style.display = 'none';
            successStatus.style.display = 'none';
            errorStatus.style.display = 'none';
            progressContainer.style.display = 'none';
            fileInfo.style.display = 'none';

            // ============= URL转换功能 =============

            // URL转换按钮点击事件
            convertUrlBtn.addEventListener('click', function () {
                const url = urlInput.value.trim();
                if (!url) {
                    showError('请输入有效的URL地址');
                    return;
                }

                // 验证URL格式
                try {
                    new URL(url);
                } catch (e) {
                    showError('请输入有效的URL地址');
                    return;
                }

                convertUrl(url);
            });

            // 处理URL转换请求
            function convertUrl(url) {
                // 重置状态
                processingStatus.style.display = 'block';
                successStatus.style.display = 'none';
                errorStatus.style.display = 'none';
                progressContainer.style.display = 'none'; // URL转换不需要进度条

                const xhr = new XMLHttpRequest();

                xhr.onload = function () {
                    if (xhr.status === 200) {
                        // 处理成功响应
                        processingStatus.style.display = 'none';
                        successStatus.style.display = 'block';

                        // 创建下载链接
                        const blob = new Blob([xhr.response], { type: 'text/markdown' });
                        const blobUrl = window.URL.createObjectURL(blob);
                        const a = document.createElement('a');
                        a.href = blobUrl;

                        // 从URL生成文件名
                        try {
                            const domain = new URL(url).hostname;
                            // 清理域名中的特殊字符
                            let safeName = domain.replace(/[^a-zA-Z0-9\u4e00-\u9fa5]/g, '');
                            // 如果清理后为空，使用默认名称
                            if (!safeName) safeName = 'webpage';
                            a.download = safeName + '.md';
                        } catch (e) {
                            a.download = 'webpage.md';
                        }

                        document.body.appendChild(a);
                        a.click();

                        // 清理
                        window.URL.revokeObjectURL(blobUrl);
                        document.body.removeChild(a);
                    } else {
                        processingStatus.style.display = 'none';
                        try {
                            const error = JSON.parse(xhr.responseText);
                            showError(error.detail || '转换失败');
                        } catch (e) {
                            showError('服务器错误');
                        }
                    }
                };

                xhr.onerror = function () {
                    processingStatus.style.display = 'none';
                    showError('网络错误');
                };

                // 发送请求到 /convertPage/ 接口
                xhr.open('POST', `/convertPage/?url=${encodeURIComponent(url)}`);
                xhr.responseType = 'blob'; // 重要：接收二进制响应
                xhr.send();
            }

            // ============= 原有文件上传功能 =============

            // 点击区域选择文件
            dropZone.addEventListener('click', function (e) {
                if (e.target !== fileInput) {
                    fileInput.click();
                }
            });

            // 选择文件按钮
            browseBtn.addEventListener('click', function (e) {
                e.stopPropagation();
                fileInput.click();
            });

            // 文件选择事件
            fileInput.addEventListener('change', function () {
                if (fileInput.files.length) {
                    handleFile(fileInput.files[0]);
                }
            });

            // 拖拽事件
            ['dragenter', 'dragover', 'dragleave', 'drop'].forEach(eventName => {
                dropZone.addEventListener(eventName, preventDefaults, false);
            });

            function preventDefaults(e) {
                e.preventDefault();
                e.stopPropagation();
            }

            ['dragenter', 'dragover'].forEach(eventName => {
                dropZone.addEventListener(eventName, highlight, false);
            });

            ['dragleave', 'drop'].forEach(eventName => {
                dropZone.addEventListener(eventName, unhighlight, false);
            });

            function highlight() {
                dropZone.classList.add('dragover');
            }

            function unhighlight() {
                dropZone.classList.remove('dragover');
            }

            // 处理拖放的文件
            dropZone.addEventListener('drop', function (e) {
                const dt = e.dataTransfer;
                const files = dt.files;

                if (files.length) {
                    handleFile(files[0]);
                }
            });

            // 处理文件
            function handleFile(file) {
                // 验证文件大小 (50MB)
                const maxSize = 50 * 1024 * 1024; // 50MB
                if (file.size > maxSize) {
                    showError(`文件过大（最大支持${maxSize / 1024 / 1024}MB）`);
                    return;
                }

                // 显示文件信息
                fileName.textContent = file.name;
                fileSize.textContent = formatFileSize(file.size);
                fileInfo.style.display = 'block';

                // 上传文件
                uploadFile(file);
            }

            // 上传文件
            function uploadFile(file) {
                const formData = new FormData();
                formData.append('file', file);

                // 重置状态
                processingStatus.style.display = 'block';
                successStatus.style.display = 'none';
                errorStatus.style.display = 'none';
                progressContainer.style.display = 'block';
                progressBar.style.width = '0%';

                const xhr = new XMLHttpRequest();

                // 进度事件
                xhr.upload.onprogress = function (e) {
                    if (e.lengthComputable) {
                        const percentComplete = (e.loaded / e.total) * 100;
                        progressBar.style.width = percentComplete + '%';
                    }
                };

                xhr.onload = function () {
                    progressContainer.style.display = 'none';

                    if (xhr.status === 200) {
                        // 处理成功响应
                        processingStatus.style.display = 'none';
                        successStatus.style.display = 'block';

                        // 创建下载链接
                        const blob = new Blob([xhr.response], { type: 'text/markdown' });
                        const url = window.URL.createObjectURL(blob);
                        const a = document.createElement('a');
                        a.href = url;

                        // 关键修复：确保所有文档类型都以.md结尾
                        // 1. 移除原始文件名中的特殊字符
                        let safeName = file.name.replace(/[^a-zA-Z0-9\u4e00-\u9fa5._-]/g, '');
                        // 2. 移除任何现有扩展名
                        safeName = safeName.replace(/\.[^/.]+$/, "");
                        // 3. 添加.md扩展名
                        safeName = safeName + '.md';

                        a.download = safeName;
                        document.body.appendChild(a);
                        a.click();

                        // 清理
                        window.URL.revokeObjectURL(url);
                        document.body.removeChild(a);
                    } else {
                        processingStatus.style.display = 'none';
                        try {
                            const error = JSON.parse(xhr.responseText);
                            showError(error.detail || '转换失败');
                        } catch (e) {
                            showError('服务器错误');
                        }
                    }
                };

                xhr.onerror = function () {
                    progressContainer.style.display = 'none';
                    processingStatus.style.display = 'none';
                    showError('网络错误');
                };

                // 发送请求
                xhr.open('POST', '/uploadfile/');
                xhr.responseType = 'blob'; // 重要：接收二进制响应
                xhr.send(formData);
            }

            // 显示错误
            function showError(message) {
                errorStatus.textContent = '转换失败: ' + message;
                errorStatus.style.display = 'block';

                // 5秒后自动隐藏错误
                setTimeout(() => {
                    errorStatus.style.display = 'none';
                }, 5000);
            }

            // 格式化文件大小
            function formatFileSize(bytes) {
                if (bytes === 0) return '0 Bytes';

                const k = 1024;
                const sizes = ['Bytes', 'KB', 'MB', 'GB'];
                const i = Math.floor(Math.log(bytes) / Math.log(k));

                return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
            }
        });
    </script>
</body>

</html>

简单起见, 就不用 nginx 部署前端页面了, 直接挂到 FastAPI 服务上

main.py
app.mount("/static", StaticFiles(directory="static"), name="static")


@app.get("/")
async def read_root(request: Request):
    return Response(
        content=open("static/index.html", "r", encoding="utf-8").read(),
        media_type="text/html"
    )

在浏览器访问 localhost:8000

img

打包成 Docker 镜像​

Dockerfile 配置

Dockerfile
FROM python:3.12-slim-bullseye

ENV DEBIAN_FRONTEND=noninteractive
ENV FFMPEG_PATH=/usr/bin/ffmpeg

ENV PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ \
    PIP_TRUSTED_HOST=mirrors.aliyun.com \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

RUN sed -i "s@deb.debian.org@mirrors.aliyun.com@g" /etc/apt/sources.list

# Runtime dependency
RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ffmpeg

# Cleanup
RUN rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . /app
RUN pip --no-cache-dir install markitdown[all] fastapi uvicorn[standard] python-multipart

# Default USERID and GROUPID
ARG USERID=nobody
ARG GROUPID=nogroup

USER $USERID:$GROUPID

ENTRYPOINT [ "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
docker build . -t linrepo/markitdown-server:latest

Docker 运行服务​

docker run -it --rm -p 8000:8000 linrepo/markitdown-server

在浏览器访问 localhost:8000

评价​

MarkItDown 现在还处于 v0.1.3 版本, 项目不算成熟, 转换效果只能说属于能用, 期待后续继续迭代吧

参考​

]]> lintech1024@hotmail.com (小林) 开源项目 Python <![CDATA[Git 设置代理]]> https://blog.lintech1024.com/git-proxy https://blog.lintech1024.com/git-proxy Wed, 10 Sep 2025 00:00:00 GMT 用了这么久 Git 不知道使用代理需要主动设置, 直到今天死活推不上代码到 GitHub 😂

princess.png

添加全局代理​

git config --global http.proxy "http://127.0.0.1:7890"
git config --global https.proxy "http://127.0.0.1:7890"
提示

Windows 系统用双引号, Linux 系统要用单引号

验证代理设置​

git config --global --get http.proxy
git config --global --get https.proxy

取消代理​

git config --global --unset http.proxy
git config --global --unset https.proxy

临时绕过代理​

unset http_proxy
unset https_proxy

在命令中临时指定代理​

git -c http.proxy="http://127.0.0.1:7890" clone https://github.com/user/repo.git

参考​

]]> lintech1024@hotmail.com (小林) Git <![CDATA[Dev Container 教程 (二) 使用预构建加速流程]]> https://blog.lintech1024.com/devcontainer-prebuild https://blog.lintech1024.com/devcontainer-prebuild Tue, 09 Sep 2025 00:00:00 GMT 我在之前的文章介绍了 Dev Container 的基本使用, 但容器构建耗时过长的问题还未探讨, 本文将通过预构建(prebuild)技术, 彻底解决这一痛点

messenger-showing.png

前置条件​

简单示例​

下面以 Go 开发环境为例, 演示如何配置一个基本的 Dev Container

新建 go-prebuild 目录并添加下面文件

.devcontainer/devcontainer.json
{
    "name": "Go",
    "image": "mcr.microsoft.com/devcontainers/go:1-1.24-bookworm",
    "features": {
        "ghcr.io/mrsimonemms/devcontainers/cobra-cli:1": {}
    },
    "customizations": {
        "vscode": {
            "settings": {
                "window.newWindowProfile": "Default", // 新窗口使用的配置文件, 只能在"默认配置文件"中设置
                "files.autoSave": "afterDelay", // 自动保存文件
                "editor.formatOnSave": true, // 保存时自动格式化
                "files.simpleDialog.enable": true, // 简单对话框, ctrl+n 新建文件时不再弹出对话框
                "editor.insertSpaces": true, // 使用空格代替制表符
                "editor.tabSize": 4, // 缩进空格数
                "editor.autoClosingDelete": "always", // 删除左括号时总是自动删除右括号
                "editor.minimap.autohide": "mouseover", // 鼠标不在缩略图上时隐藏缩略图, 鼠标在缩略图上时显示缩略图
                "terminal.integrated.cursorStyle": "underline", // 终端光标样式使用下划线
                "explorer.confirmDelete": false, // 删除文件时不再弹出确认对话框
                "explorer.confirmDragAndDrop": false, // 拖放移动文件或文件夹时不再弹出确认对话框
                "vsicons.dontShowNewVersionMessage": true, // 不显示新版本消息
                "workbench.iconTheme": "vscode-icons" // 使用 vscode-icons 图标主题
            },
            "extensions": [
                "mhutchie.git-graph", // Git 图形化视图
                "eamodio.gitlens", // Git 增强工具, 主要为了能显示代码作者
                "vscode-icons-team.vscode-icons", // VSCode 图标主题
                "github.copilot", // GitHub Copilot, AI 代码补全
                "github.copilot-chat" // GitHub Copilot Chat, AI 聊天助手
            ]
        }
    },
    "containerEnv": {
        "GOPROXY": "https://goproxy.io,direct"
    },
    "runArgs": [
        "--name",
        "go-container"
    ]
}

关键参数解析

  • features: 配置添加功能模块, 这里添加Go命令行工具 cobra-cli
  • customizations: 个性化配置, 这里提供我的VSCocde设置和插件以供参考
  • containerEnv: 设置环境变量, 这里通过环境变量设置Go镜像源
  • runArgs: 传递给 Docker CLI 的参数, 这里给启动容器命名为 go-container, 方便查找

Features​

Features 是 Dev Container 一项比较强大的能力, 它将常见的开发环境配置封装为可复用的模块, 使环境配置变得简单高效

Features 核心优势

  1. 模块化设计
  • 将常见开发环境配置拆分为独立的、可组合的功能单元
  • 每个 Feature 专注于单一职责(如安装特定语言运行时、配置工具链等)
  • 可根据项目需求灵活组合不同 Features
  1. 简化配置
  • 无需再编写复杂的 Dockerfile 或处理繁琐的安装脚本
  • 通过简单的声明式语法在 devcontainer.json 中添加功能

在 VSCode 中，可以通过可视化界面轻松添加 Features:

feature-devcontainer.gif

官方和社区提供了很多常用的 Features, 具体可以参考 Available Dev Container Features

添加插件​

Dev Container 支持在容器内预装 VS Code 插件, 确保开发环境开箱即用. 配置插件有两种方式:

  1. 手动添加: 将插件 ID 添加到 devcontainer.json 的 extensions 数组中
  2. 可视化操作: 在 VSCode 界面中管理插件

extensions-devcontainer.gif

推荐实践: 对于团队项目, 建议在 devcontainer.json 中明确指定必要插件, 确保所有成员使用一致的开发环境

预构建​

安装 Dev Container CLI​

npm install -g @devcontainers/cli

构建自定义镜像​

在项目目录执行以下命令构建镜像:

devcontainer build --workspace-folder . --image-name go-devcontainer:0.1

img

构建成功后, 您将获得一个包含完整开发环境的 Docker 镜像, 可直接用于创建 Dev Container

使用预构建镜像​

新建 go-demo 目录, 创建 devcontainer.json 文件

.devcontainer/devcontainer.json
{
    "name": "go-demo",
    "image": "go-devcontainer:0.1"
}

通过 Ctrl + Shift + P 打开命令面板, 输入 "Reopen in Container" 并执行, VSCode 将使用预构建镜像启动开发环境

img

静待 VSCode 启动 VSCode Server, 下载并激活必要的插件, 接下来就可以愉快的开发了

镜像分发策略​

预构建的镜像可推送到私有或公共镜像仓库, 解决网络环境限制问题:

docker tag go-devcontainer:0.1 registry.cn-hangzhou.aliyuncs.com/lepo/go-devcontainer:0.1
docker push registry.cn-hangzhou.aliyuncs.com/lepo/go-devcontainer:0.1

也可以直接一步到位, 构建镜像并推送到镜像仓库

devcontainer build --workspace-folder . --push true --image-name <my_image_name>:<optional_image_version>

离线模式​

预构建虽解决了镜像构建问题, 但仍需要网络下载 VSCode Server 和插件. 以下方法可实现真正的离线开发环境

直接将容器打包成镜像​

  1. 首先启动一个已配置好的容器
  2. 将运行中的容器保存为新镜像

我们在先前的示例中已启动一个命名为 go-container 的容器, 可以直接将其保存为镜像

docker commit go-container go-devcontainer-offline:0.1

使用离线镜像​

新建 go-demo-offline 目录, 创建 devcontainer.json 文件

.devcontainer/devcontainer.json
{
    "name": "go-demo-offline",
    "image": "go-devcontainer-offline:0.1"
}

此时, 即使完全断开网络连接, 也能成功启动开发环境, 并且相关的环境配置, 插件安装均已准备就绪, 开箱即用

重要安全提示

此方法会将容器内所有数据(包括可能的敏感信息)打包到镜像中, 请务必:

  1. 在提交前清理容器内的敏感数据
  2. 避免将包含用户凭证的容器提交到共享仓库

保存镜像​

制作的镜像同样可以推送到私有仓库方便随时拉取开发环境, 或者可以保存为 tar 文件, 存到 U 盘随身携带

docker save -o go-devcontainer-offline.tar go-devcontainer-offline:0.1

后续可直接恢复镜像

docker load -i go-devcontainer-offline.tar

以后你就能火箭般🚀配好自己的开发环境, 从此成为最靓的仔 😎

参考​

]]> lintech1024@hotmail.com (小林) 基础教程 开发环境 VSCode Docker <![CDATA[Dev Container 教程 (一) 基本使用]]> https://blog.lintech1024.com/devcontainer-tutorial https://blog.lintech1024.com/devcontainer-tutorial Mon, 01 Sep 2025 00:00:00 GMT 作为开发者, 我们常面临这样的挑战：如何让系统环境、编程工具链、依赖库及编辑器配置在不同机器上保持一致？如何避免每次搭建开发环境浪费大量时间? 本文介绍的 Dev Containers 就为了解决这些问题, 让你一键启动一个标准化的开发环境

messenger-running.png

什么是 Dev Container​

Dev Container 是一种将容器用作完整开发环境的技术方案. 简单表示

开发环境=devcontainer.json+Docker+VSCode开发环境 = devcontainer.json + Docker + VSCode

为什么使用 Dev Container​

  • 环境一致性：无论怎样更换设备, 只需拉取容器即可获得完全一致的开发环境, 避免繁琐的环境配置过程
  • 团队协作：确保所有团队成员使用完全相同的开发环境, 消除"我的机器可以, 你的不行"的常见问题
  • 贴近生产：提供纯净的 Linux 环境, 更接近实际生产环境, 减少环境差异导致的问题
  • 流程简化：自动化环境部署, 简化开发流程, 提升开发效率
  • 工具集成：内置常用开发工具, 自动安装 VSCode 插件, 开箱即用
  • 配置同步：确保 VSCode 设置和插件在所有环境中保持一致
  • 远程开发：支持远程开发场景, 使开发环境与本地机器解耦

前置条件​

快速入门​

从零开始创建一个 Dev Container​

下面以创建 Python 开发环境为例, 演示如何从零开始创建 Dev Container

new-devcontainers

  • 点击 VSCode 左下角的 Open a Remote Window 按钮
  • 在弹出菜单中选择 New Dev Container...
  • 在模板列表中输入 python 进行过滤
  • 输入容器名称(如 python-demo)
  • 等待 Docker 拉取容器镜像(可点击 show log 查看进度)
  • 成功后, VSCode 将打开新窗口, 表示已进入 Dev Container 环境
  • 在终端输入 python --version 确认 Python 环境是否可用

此时, 工作目录下会生成 Dev Container 配置文件：

.devcontainer/devcontainer.json
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/python
{
    "name": "Python 3",
    // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
    "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye"

    // Features to add to the dev container. More info: https://containers.dev/features.
    // "features": {},

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    // "forwardPorts": [],

    // Use 'postCreateCommand' to run commands after the container is created.
    // "postCreateCommand": "pip3 install --user -r requirements.txt",

    // Configure tool-specific properties.
    // "customizations": {},

    // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
    // "remoteUser": "root"
}

Dev Container 做了什么事?

img

  • 拉取配置中 image 字段指定的 Docker 镜像
  • 如使用 Dockerfile 或 Features, 会自动构建定制化镜像

img

  • 启动 Docker 容器作为开发环境
  • 容器关闭后自动销毁, 确保环境纯净

img

  • 创建与容器名称相同的持久化卷
  • 将持久化卷挂载到工作目录, 确保数据不丢失

img

  • 自动安装配置模板中指定的 VSCode 插件
  • 开箱即用, 无需手动配置开发环境

用 Dev Container 打开已有项目​

exist-devcontainers

以下演示如何为现有项目配置 Dev Container(以 Golang Gin 项目为例):

  • 点击左下角的 Open a Remote Window 按钮
  • 选择 Add Dev Container Configuration Files...
  • 选择 Add Configuration to workspace 将配置文件存放到工作目录
  • 在模板列表中输入 go 进行过滤
  • 选择 Go 版本(如 1.24-bookworm)
  • 按需选择 Features(可跳过)
  • 点击 Reopen in Container 在新窗口打开容器

生成的配置文件如下:

.devcontainer/devcontainer.json
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/go
{
    "name": "Go",
    // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
    "image": "mcr.microsoft.com/devcontainers/go:1-1.24-bookworm"

    // Features to add to the dev container. More info: https://containers.dev/features.
    // "features": {},

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    // "forwardPorts": [],

    // Use 'postCreateCommand' to run commands after the container is created.
    // "postCreateCommand": "go version",

    // Configure tool-specific properties.
    // "customizations": {},

    // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
    // "remoteUser": "root"
}

同样预装了相关插件, 预装哪些插件根据配置模板会有不同

img

注意

使用 Dev Container 打开已有项目时, 不会创建持久化卷, 而是直接将本地目录挂载到容器工作目录. 这意味着在容器中对工作目录的修改会直接反映到本地文件系统

配置完成后, 可运行项目并访问 http://localhost:8080/ping

go run main.go

Dev Container 会自动将容器内部端口转发到本地, 无需手动配置端口映射

img

配置 devcontainer.json​

下面以 Python FastAPI 项目为例, 优化第一个示例的 devcontainer.json 配置, 提升开发体验

.devcontainer/devcontainer.json
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/python
{
    "name": "Python 3",
    // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
    "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
    // Features to add to the dev container. More info: https://containers.dev/features.
    // "features": {},
    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    // "forwardPorts": [],
    // Use 'postCreateCommand' to run commands after the container is created.
    // "postCreateCommand": "pip3 install --user -r requirements.txt",
    // Configure tool-specific properties.
    "customizations": {
        "vscode": {
            "settings": {
                "window.newWindowProfile": "Default", // 新窗口使用的配置文件, 只能在"默认配置文件"中设置
                "files.autoSave": "afterDelay", // 自动保存文件
                "editor.formatOnSave": true, // 保存时自动格式化
                "files.simpleDialog.enable": true, // 简单对话框, ctrl+n 新建文件时不再弹出对话框
                "editor.insertSpaces": true, // 使用空格代替制表符
                "editor.tabSize": 4, // 缩进空格数
                "editor.autoClosingDelete": "always", // 删除左括号时总是自动删除右括号
                "editor.minimap.autohide": "mouseover", // 鼠标不在缩略图上时隐藏缩略图, 鼠标在缩略图上时显示缩略图
                "terminal.integrated.cursorStyle": "underline", // 终端光标样式使用下划线
                "explorer.confirmDelete": false, // 删除文件时不再弹出确认对话框
                "explorer.confirmDragAndDrop": false, // 拖放移动文件或文件夹时不再弹出确认对话框
                "vsicons.dontShowNewVersionMessage": true, // 不显示新版本消息
                "workbench.iconTheme": "vscode-icons" // 使用 vscode-icons 图标主题
            },
            "extensions": [
                "piotrpalarz.vscode-gitignore-generator", // .gitignore 文件生成器
                "mhutchie.git-graph", // Git 图形化视图
                "eamodio.gitlens", // Git 增强工具, 主要为了能显示代码作者
                "ms-python.vscode-pylance", // Python 语言支持
                "vscode-icons-team.vscode-icons", // VSCode 图标主题
                "github.copilot", // GitHub Copilot, AI 代码补全
                "github.copilot-chat" // GitHub Copilot Chat, AI 聊天助手
            ]
        }
    },
    // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
    // "remoteUser": "root"
    "containerEnv": {
        "PIP_INDEX_URL": "https://mirrors.aliyun.com/pypi/simple/",
        "PIP_TRUSTED_HOST": "mirrors.aliyun.com"
    },
    "postCreateCommand": "pip install -U pip && pip install fastapi uvicorn[standard]",
	"postStartCommand": "uvicorn main:app --reload"
}
  • name: 必填项, 会显示在 VSCode 的 UI 上
  • image: 基础 Docker 镜像地址
  • customizations: 跟编辑器相关的配置, VSCode 的相关设置可以在这里配置, 我这里修改 settings.json 的一些值和预装插件, VSCode 配置可以参考我之前的文章
  • containerEnv: 注入容器的环境变量, 这里通过环境变量设置 pip 使用阿里源
  • postCreateCommand: 每次容器构建完成前执行的最后一段命令, 我们在这里配置安装项目所需的依赖库
  • postStartCommand: 每次容器启动前执行的最后一段命令, 可以在这里配置启动服务的命令
  • 更多配置项可以参考Dev Container 官方文档

配置完成后, 点击左下角按钮选择 Rebuild Container 重建容器:

rebuild-devcontainer

容器构建完成后, Dev Container 会自动启动服务并映射端口, 可点击 Open in Browser 直接访问应用

img

总结​

本文通过示例介绍了 Dev Container 的基本使用, 为避免篇幅过长, 我将在后续文章介绍 Dev Container 更多高级用法

更多​

参考​

]]> lintech1024@hotmail.com (小林) 基础教程 开发环境 VSCode Docker <![CDATA[一份珍藏多年的 VSCode 配置]]> https://blog.lintech1024.com/vscode-profile https://blog.lintech1024.com/vscode-profile Thu, 28 Aug 2025 00:00:00 GMT 记录下最符合个人习惯的 VSCode 配置, 只修改非默认项以保持配置文件的简洁. 可能会随着使用不断补充更新.

hero-poster-dark

Settings​

settings.json
{
    "window.newWindowProfile": "Default", // 新窗口使用的配置文件, 只能在"默认配置文件"中设置
    "files.autoSave": "afterDelay", // 自动保存文件
    "editor.formatOnSave": true, // 保存时自动格式化
    "files.simpleDialog.enable": true, // 简单对话框, ctrl+n 新建文件时不再弹出对话框
    "editor.insertSpaces": true, // 使用空格代替制表符
    "editor.tabSize": 4, // 缩进空格数
    "editor.autoClosingDelete": "always", // 删除左括号时总是自动删除右括号
    "editor.minimap.autohide": "mouseover", // 鼠标不在缩略图上时隐藏缩略图，鼠标在缩略图上时显示缩略图
    "terminal.integrated.cursorStyle": "underline", // 终端光标样式使用下划线
    "explorer.confirmDelete": false, // 删除文件时不再弹出确认对话框
    "explorer.confirmDragAndDrop": false, // 拖放移动文件或文件夹时不再弹出确认对话框
    "vsicons.dontShowNewVersionMessage": true, // 不显示新版本消息
    "workbench.iconTheme": "vscode-icons", // 使用 vscode-icons 图标主题
}

键盘快捷键​

keybindings.json
[
    {
        "key": "ctrl+k ctrl+u",
        "command": "editor.action.transformToUppercase" // 转为大写
    },
    {
        "key": "ctrl+k ctrl+l",
        "command": "editor.action.transformToLowercase" // 转为小写
    }
]

插件​

extensions.json
{
    "recommendations": [
        "piotrpalarz.vscode-gitignore-generator", // .gitignore 文件生成器
        "mhutchie.git-graph", // Git 图形化视图
        "eamodio.gitlens", // Git 增强工具, 主要为了能显示代码作者
        "golang.go", // Go 语言支持
        "ritwickdey.liveserver", // HTML 实时预览
        "ms-python.vscode-pylance", // Python 语言支持
        "mushan.vscode-paste-image", // 支持粘贴图片到 Markdown
        "vscode-icons-team.vscode-icons", // VSCode 图标主题
        "github.copilot", // GitHub Copilot, AI 代码补全
        "github.copilot-chat" // GitHub Copilot Chat, AI 聊天助手
    ]
}
]]> lintech1024@hotmail.com (小林) 开发环境 VSCode